@nmnmcc/ability 0.3.0 → 1.0.1

package/dist/HttpApi.d.ts

@@ -1,14 +1,29 @@
-import { ActionOf, Any, Kind, ValueOf } from "./Domain.js";
-import { Forbidden, Pending, PolicyUnavailable } from "./internal/authorizer.js";
-import { AnyServiceClass } from "./Authorizer.js";
+import { Any, CommonAction, Kind, ValueOf } from "./Domain.js";
+import { Scope } from "./Policy.js";
+import { AnyServiceClass, Forbidden, Pending, PolicyUnavailable } from "./Authorizer.js";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
 /**
- * One check that an endpoint needs: an action on a kind of resource. With
- * `load`, the middleware loads the resource value from the path parameters
- * and checks the action on that value. Without `load`, it checks the action
- * on the kind.
+ * The path parameters of a request.
+ *
+ * @stability unstable
+ * @category models
+ * @since 1.0.0
+ */
+export type Params = Readonly<Record<string, string | undefined>>;
+/**
+ * One check that an endpoint needs: an action on a kind of resource.
+ * - With `load`, the middleware loads the resource value from the path
+ *   parameters and checks the action on that value.
+ * - With `within`, it makes a scope from the path parameters and checks the
+ *   action on every value in the scope.
+ * - With `list`, the endpoint gives a list. The handler gets the list query
+ *   with `Authorizer.filter`, so the middleware checks nothing, unless
+ *   `nonEmpty` is true: then it fails when the principal may act on no value
+ *   in the scope.
+ * - With none of them, it checks the action on every value of the kind.
  *
  * @stability unstable
  * @category models
@@ -17,7 +32,11 @@ import * as Layer from "effect/Layer";
 export interface Requirement {
   readonly action: string;
   readonly kind: string;
-  readonly load?: (params: Readonly<Record<string, string | undefined>>) => Effect.Effect<object, unknown, unknown>;
+  readonly load?: (params: Params) => Effect.Effect<object, unknown, unknown>;
+  readonly within?: (params: Params) => unknown;
+  readonly list?: {
+    readonly nonEmpty: boolean;
+  };
 }
 declare const Required_base: Context.ServiceClass<Required, "@nmnmcc/ability/HttpApi/Required", readonly Requirement[]>;
 /**
@@ -43,10 +62,17 @@ declare const GroupRequired_base: Context.ServiceClass<GroupRequired, "@nmnmcc/a
 export declare class GroupRequired extends GroupRequired_base {}
 /**
  * Makes a {@link Requirement} with the types of an authorizer. The action must
- * be an action of the kind, and `load` must give a value of the kind.
+ * be an action of the kind, also when the kind has a union type.
  *
- * `load` may fail. Its errors must be errors of the middleware, and the
- * services that it needs must be given to {@link layer}.
+ * The last argument is one of:
+ * - a `load` function, which must give a value of the kind. It may fail. Its
+ *   errors must be errors of the middleware, and the services that it needs
+ *   must be given to {@link layer}.
+ * - `{ within }`, a function from the path parameters to a scope. Use it for
+ *   an act on a part of the kind, such as a new value with no id yet:
+ *   `{ within: (params) => ($) => $.under("org", params.org ?? null) }`. A path
+ *   parameter may be `undefined`, and a scope with `undefined` in it is a
+ *   defect, so give a value for it.
  *
  * @stability unstable
  * @category constructors
@@ -54,61 +80,79 @@ export declare class GroupRequired extends GroupRequired_base {}
  */
 export declare const requires: <A extends {
   readonly domain: Any;
-}, const K extends Kind<A["domain"]>>(authorizer: A, action: ActionOf<A["domain"], K>, kind: K, load?: (params: Readonly<Record<string, string | undefined>>) => Effect.Effect<ValueOf<A["domain"], K>, unknown, unknown>) => Requirement;
+}, const K extends Kind<A["domain"]>>(authorizer: A, action: CommonAction<A["domain"], K>, kind: K, how?: ((params: Params) => Effect.Effect<ValueOf<A["domain"], K>, unknown, unknown>) | {
+  readonly within: (params: Params) => Scope<A["domain"], K>;
+}) => Requirement;
+/**
+ * Makes a {@link Requirement} for an endpoint that gives a list. The middleware
+ * does not check that the principal may act on every value, because the list
+ * shows only the values that it may act on. The handler gets the list query
+ * with `Authorizer.filter`, with the same scope.
+ *
+ * When the principal may act on no value, the list is empty: that is not an
+ * error, so a client does not learn that hidden values are there. With
+ * `nonEmpty: true`, the middleware fails with `Forbidden` in that case. It
+ * also fails when the coverage is `Unknown`, because then it can not say that
+ * the list has a value.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const lists: <A extends {
+  readonly domain: Any;
+}, const K extends Kind<A["domain"]>>(authorizer: A, action: CommonAction<A["domain"], K>, kind: K, options?: {
+  readonly within?: (params: Params) => Scope<A["domain"], K>;
+  readonly nonEmpty?: boolean;
+}) => Requirement;
 /**
  * The errors of the middleware, with HTTP status codes: 403 for
  * `Forbidden`, 503 for `PolicyUnavailable`, and 409 for `Pending`.
  *
+ * The body of a `PolicyUnavailable` response has only its `_tag`. The cause
+ * may have private details, such as an error from the database, so it stays
+ * on the server.
+ *
  * @stability unstable
  * @category errors
  * @since 0.3.0
  */
-export declare const errors: readonly [import("effect/Schema").decodeTo<import("effect/Schema").declareConstructor<Forbidden, {
+export declare const errors: readonly [Schema.decodeTo<Schema.declareConstructor<Forbidden, {
   readonly _tag: "Forbidden";
   readonly action: string;
   readonly kind: string;
   readonly field?: string;
   readonly reason?: string;
-}, readonly [import("effect/Schema").TaggedStruct<"Forbidden", {
-  readonly action: import("effect/Schema").String;
-  readonly kind: import("effect/Schema").String;
-  readonly field: import("effect/Schema").optionalKey<import("effect/Schema").String>;
-  readonly reason: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+}, readonly [Schema.TaggedStruct<"Forbidden", {
+  readonly action: Schema.String;
+  readonly kind: Schema.String;
+  readonly field: Schema.optionalKey<Schema.String>;
+  readonly reason: Schema.optionalKey<Schema.String>;
 }>], {
   readonly _tag: "Forbidden";
   readonly action: string;
   readonly kind: string;
   readonly field?: string;
   readonly reason?: string;
-}>, import("effect/Schema").TaggedStruct<"Forbidden", {
-  readonly action: import("effect/Schema").String;
-  readonly kind: import("effect/Schema").String;
-  readonly field: import("effect/Schema").optionalKey<import("effect/Schema").String>;
-  readonly reason: import("effect/Schema").optionalKey<import("effect/Schema").String>;
-}>, never, never>, import("effect/Schema").decodeTo<import("effect/Schema").declareConstructor<PolicyUnavailable, {
-  readonly _tag: "PolicyUnavailable";
-  readonly cause: import("effect/Schema").Json;
-}, readonly [import("effect/Schema").TaggedStruct<"PolicyUnavailable", {
-  readonly cause: import("effect/Schema").Defect;
-}>], {
-  readonly _tag: "PolicyUnavailable";
-  readonly cause: unknown;
-}>, import("effect/Schema").TaggedStruct<"PolicyUnavailable", {
-  readonly cause: import("effect/Schema").Defect;
-}>, never, never>, import("effect/Schema").decodeTo<import("effect/Schema").declareConstructor<Pending, {
+}>, Schema.TaggedStruct<"Forbidden", {
+  readonly action: Schema.String;
+  readonly kind: Schema.String;
+  readonly field: Schema.optionalKey<Schema.String>;
+  readonly reason: Schema.optionalKey<Schema.String>;
+}>, never, never>, Schema.decodeTo<Schema.declare<PolicyUnavailable, PolicyUnavailable>, Schema.TaggedStruct<"PolicyUnavailable", {}>, never, never>, Schema.decodeTo<Schema.declareConstructor<Pending, {
   readonly _tag: "Pending";
   readonly ticket: string;
   readonly reason?: string;
-}, readonly [import("effect/Schema").TaggedStruct<"Pending", {
-  readonly ticket: import("effect/Schema").String;
-  readonly reason: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+}, readonly [Schema.TaggedStruct<"Pending", {
+  readonly ticket: Schema.String;
+  readonly reason: Schema.optionalKey<Schema.String>;
 }>], {
   readonly _tag: "Pending";
   readonly ticket: string;
   readonly reason?: string;
-}>, import("effect/Schema").TaggedStruct<"Pending", {
-  readonly ticket: import("effect/Schema").String;
-  readonly reason: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+}>, Schema.TaggedStruct<"Pending", {
+  readonly ticket: Schema.String;
+  readonly reason: Schema.optionalKey<Schema.String>;
 }>, never, never>];
 /**
  * Makes the layer of an authorization middleware. The middleware reads the

package/dist/HttpApi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HttpApi.d.ts","names":["Domain.Any","Domain.Kind","Domain.ActionOf","Domain.ValueOf","_$__internal_authorizer_ts0.Forbidden","_$__internal_authorizer_ts0.PolicyUnavailable","_$__internal_authorizer_ts0.Pending","Authorizer.AnyServiceClass"],"sources":["../src/HttpApi.ts"],"mappings":";;;;;;;;;;;;;;;;iBAgDiB;WACP;WACA;WACA,QACR,QAAQ,SAAS,wCACb,OAAO;;;;;;;;;;qBAUA,iBAAiB;;WAgBb,MAAA,cAAc;WACb,OAAA,cAAc;;;;;;;;;;qBAJnB,sBAAsB;;;;;;;;;;;;qBAmBtB,WACZ;WAAqB,QAAQA;SACvB,UAAUC,KAAY,cAE5B,YAAY,GACZ,QAAQC,SAAgB,aAAa,IACrC,MAAM,GACN,QACC,QAAQ,SAAS,wCACb,OAAO,OAAOC,QAAe,aAAa,0BAC3C;;;;;;;;;qBAUQ,0CAAM,iCAAA,mBAANC;;;;;;;;;;;;;;;;;;;;;;2C,oDAAMC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAoBN,QACZ,MACA,mBACA,UAAUE,iBACV,WAEA,YAAY,QAAQ,aAAa,MAAM,UACvC,YAAY,MACR,MAAM,MACV,cAEC,UAAU,QAAQ,UAAU,UAAU,aAAa"}
+{"version":3,"file":"HttpApi.d.ts","names":["Domain.Any","Domain.Kind","Domain.CommonAction","Domain.ValueOf","Policy.Scope","Authorizer.Forbidden","Authorizer.PolicyUnavailable","Authorizer.Pending","Authorizer.AnyServiceClass"],"sources":["../src/HttpApi.ts"],"mappings":";;;;;;;;;;;;;;YAyDY,SAAS,SAAS;;;;;;;;;;;;;;;;;iBAkBb;WACP;WACA;WACA,QAAQ,QAAQ,WAAW,OAAO;WAClC,UAAU,QAAQ;WAClB;aAAkB;;;;;;;;;;;qBAUf,iBAAiB;;WAgBb,MAAA,cAAc;WACb,OAAA,cAAc;;;;;;;;;;qBAJnB,sBAAsB;;;;;;;;;;;;;;;;;;;qBA0BtB,WACZ;WAAqB,QAAQA;SACvB,UAAUC,KAAY,cAE5B,YAAY,GACZ,QAAQC,aAAoB,aAAa,IACzC,MAAM,GACN,QAEG,QAAQ,WACH,OAAO,OAAOC,QAAe,aAAa;WACpC,SAAS,QAAQ,WAAWC,MAAa,aAAa;MAChE;;;;;;;;;;;;;;;;;qBAuBQ,QACZ;WAAqB,QAAQJ;SACvB,UAAUC,KAAY,cAE5B,YAAY,GACZ,QAAQC,aAAoB,aAAa,IACzC,MAAM,GACN;WACU,UAAU,QAAQ,WAAWE,MAAa,aAAa;WACvD;MAEN;;;;;;;;;;;;;qBAuCQ,kBAAM,OAAA,SAAA,OAAA,mBAAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAyHN,QACZ,MACA,mBACA,UAAUG,iBACV,WAEA,YAAY,QAAQ,aAAa,MAAM,UACvC,YAAY,MACR,MAAM,MACV,cAEC,UAAU,QAAQ,UAAU,UAAU,aAAa"}

package/dist/HttpApi.js

@@ -1,6 +1,12 @@
+import { kindOf } from "./Resource.js";
 import { Forbidden, Pending, PolicyUnavailable } from "./Authorizer.js";
-import { layer as layer$1, requires as requires$1 } from "./internal/httpApi.js";
 import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as SchemaTransformation from "effect/SchemaTransformation";
+import { HttpRouter } from "effect/http";
 import { HttpApiSchema } from "effect/http-api";
 // src/HttpApi.ts
 /**
@@ -9,9 +15,10 @@ import { HttpApiSchema } from "effect/http-api";
 * Each endpoint says what it needs with the {@link Required} annotation. A
 * group can give a default with {@link GroupRequired}: one list for GET
 * requests and one list for all other methods. A middleware checks the
-* requirements before the handler runs. An endpoint with no annotation is a
-* defect, so a new endpoint is closed until you say what it needs. An empty
-* list means the endpoint is open.
+* requirements before the handler runs, in each group that uses it. An
+* endpoint with no annotation is a defect, so a new endpoint is closed until
+* you say what it needs. An empty list means the endpoint is open. An endpoint
+* in a group without the middleware is not checked at all.
 *
 * ```ts
 * class Authorization extends HttpApiMiddleware.Service<
@@ -19,11 +26,13 @@ import { HttpApiSchema } from "effect/http-api";
 *   { requires: Identity }
 * >()("app/Authorization", { error: HttpApi.errors }) {}
 *
-* const endpoint = HttpApiEndpoint.patch("update", "/bots/:id", { ... })
+* const endpoint = HttpApiEndpoint.patch("update", "/notes/:id", { ... })
 *   .annotate(HttpApi.Required, [
-*     HttpApi.requires(Auth, "update", "Bot", (params) => Bots.find(params.id)),
+*     HttpApi.requires(Auth, "update", "Note", (params) => Notes.find(params.id)),
 *   ])
 *
+* const notes = HttpApiGroup.make("notes").add(endpoint).middleware(Authorization)
+*
 * const AuthorizationLive = HttpApi.layer(Authorization, Auth)
 * ```
 *
@@ -52,29 +61,110 @@ var Required = class extends Context.Service()("@nmnmcc/ability/HttpApi/Required
 var GroupRequired = class extends Context.Service()("@nmnmcc/ability/HttpApi/GroupRequired") {};
 /**
 * Makes a {@link Requirement} with the types of an authorizer. The action must
-* be an action of the kind, and `load` must give a value of the kind.
+* be an action of the kind, also when the kind has a union type.
 *
-* `load` may fail. Its errors must be errors of the middleware, and the
-* services that it needs must be given to {@link layer}.
+* The last argument is one of:
+* - a `load` function, which must give a value of the kind. It may fail. Its
+*   errors must be errors of the middleware, and the services that it needs
+*   must be given to {@link layer}.
+* - `{ within }`, a function from the path parameters to a scope. Use it for
+*   an act on a part of the kind, such as a new value with no id yet:
+*   `{ within: (params) => ($) => $.under("org", params.org ?? null) }`. A path
+*   parameter may be `undefined`, and a scope with `undefined` in it is a
+*   defect, so give a value for it.
 *
 * @stability unstable
 * @category constructors
 * @since 0.3.0
 */
-const requires = requires$1;
+const requires = (_authorizer, action, kind, how) => how === void 0 ? {
+	action,
+	kind
+} : typeof how === "function" ? {
+	action,
+	kind,
+	load: how
+} : {
+	action,
+	kind,
+	within: how.within
+};
+/**
+* Makes a {@link Requirement} for an endpoint that gives a list. The middleware
+* does not check that the principal may act on every value, because the list
+* shows only the values that it may act on. The handler gets the list query
+* with `Authorizer.filter`, with the same scope.
+*
+* When the principal may act on no value, the list is empty: that is not an
+* error, so a client does not learn that hidden values are there. With
+* `nonEmpty: true`, the middleware fails with `Forbidden` in that case. It
+* also fails when the coverage is `Unknown`, because then it can not say that
+* the list has a value.
+*
+* @stability unstable
+* @category constructors
+* @since 1.0.0
+*/
+const lists = (_authorizer, action, kind, options) => ({
+	action,
+	kind,
+	list: { nonEmpty: options?.nonEmpty ?? false },
+	...options?.within === void 0 ? {} : { within: options.within }
+});
+/**
+* The Schema of a `PolicyUnavailable` response. It encodes only the `_tag`, so
+* the cause does not go to the client.
+*/
+const PolicyUnavailableResponse = Schema.TaggedStruct("PolicyUnavailable", {}).pipe(Schema.decodeTo(Schema.declare((u) => u instanceof PolicyUnavailable), SchemaTransformation.transform({
+	decode: () => PolicyUnavailable.make({ cause: void 0 }),
+	encode: () => ({ _tag: "PolicyUnavailable" })
+})));
 /**
 * The errors of the middleware, with HTTP status codes: 403 for
 * `Forbidden`, 503 for `PolicyUnavailable`, and 409 for `Pending`.
 *
+* The body of a `PolicyUnavailable` response has only its `_tag`. The cause
+* may have private details, such as an error from the database, so it stays
+* on the server.
+*
 * @stability unstable
 * @category errors
 * @since 0.3.0
 */
 const errors = [
 	Forbidden.pipe(HttpApiSchema.status(403)),
-	PolicyUnavailable.pipe(HttpApiSchema.status(503)),
+	PolicyUnavailableResponse.pipe(HttpApiSchema.status(503)),
 	Pending.pipe(HttpApiSchema.status(409))
 ];
+const makeLayer = (middleware, authorizer) => Layer.effect(middleware, Effect.gen(function* () {
+	const service = yield* authorizer;
+	const services = yield* Effect.context();
+	return Effect.fnUntraced(function* (httpEffect, options) {
+		const requirements = Option.orElse(Context.getOption(options.endpoint.annotations, Required), () => Option.map(Context.getOption(options.group.annotations, GroupRequired), (rules) => options.endpoint.method === "GET" ? rules.read : rules.write));
+		if (Option.isNone(requirements)) return yield* Effect.die(/* @__PURE__ */ new Error(`The endpoint ${options.group.identifier}.${options.endpoint.name} does not say what it needs. Give it the HttpApi.Required annotation.`));
+		const endpoint = `${options.group.identifier}.${options.endpoint.name}`;
+		yield* Effect.forEach(requirements.value, ({ action, kind, load, within, list }) => {
+			if (load !== void 0) return HttpRouter.params.pipe(Effect.flatMap((params) => Effect.provideContext(load(params), services)), Effect.filterOrElse((value) => kindOf(value) === kind, () => Effect.die(/* @__PURE__ */ new Error(`The load function of ${endpoint} gave a value that is not a ${kind}`))), Effect.flatMap((value) => service.check({
+				action,
+				resource: value
+			})));
+			const target = within === void 0 ? Effect.succeed({
+				action,
+				kind
+			}) : Effect.map(HttpRouter.params, (params) => ({
+				action,
+				kind,
+				within: within(params)
+			}));
+			if (list === void 0) return Effect.flatMap(target, (value) => service.check(value));
+			return list.nonEmpty ? target.pipe(Effect.flatMap((value) => service.coverage(value)), Effect.filterOrElse((covered) => covered._tag === "All" || covered._tag === "Some", () => Effect.fail(Forbidden.make({
+				action,
+				kind
+			})))) : Effect.void;
+		}, { discard: true });
+		return yield* httpEffect;
+	});
+}));
 /**
 * Makes the layer of an authorization middleware. The middleware reads the
 * {@link Required} and {@link GroupRequired} annotations and checks each
@@ -89,7 +179,7 @@ const errors = [
 * @category layers
 * @since 0.3.0
 */
-const layer = layer$1;
-export { GroupRequired, Required, errors, layer, requires };
+const layer = makeLayer;
+export { GroupRequired, Required, errors, layer, lists, requires };
 
 //# sourceMappingURL=HttpApi.js.map

package/dist/HttpApi.js.map

@@ -1 +1 @@
-{"version":3,"file":"HttpApi.js","names":["internal.requires","internal.layer"],"sources":["../src/HttpApi.ts"],"sourcesContent":["/**\n * Tools to check authorization in an `effect/http-api` server.\n *\n * Each endpoint says what it needs with the {@link Required} annotation. A\n * group can give a default with {@link GroupRequired}: one list for GET\n * requests and one list for all other methods. A middleware checks the\n * requirements before the handler runs. An endpoint with no annotation is a\n * defect, so a new endpoint is closed until you say what it needs. An empty\n * list means the endpoint is open.\n *\n * ```ts\n * class Authorization extends HttpApiMiddleware.Service<\n *   Authorization,\n *   { requires: Identity }\n * >()(\"app/Authorization\", { error: HttpApi.errors }) {}\n *\n * const endpoint = HttpApiEndpoint.patch(\"update\", \"/bots/:id\", { ... })\n *   .annotate(HttpApi.Required, [\n *     HttpApi.requires(Auth, \"update\", \"Bot\", (params) => Bots.find(params.id)),\n *   ])\n *\n * const AuthorizationLive = HttpApi.layer(Authorization, Auth)\n * ```\n *\n * This module is a separate entry point, `@nmnmcc/ability/HttpApi`, because\n * `effect/http-api` is not stable yet.\n *\n * @stability unstable\n * @since 0.3.0\n */\nimport * as Context from \"effect/Context\"\nimport type * as Effect from \"effect/Effect\"\nimport type * as Layer from \"effect/Layer\"\nimport { HttpApiSchema } from \"effect/http-api\"\nimport * as Authorizer from \"./Authorizer.ts\"\nimport type * as Domain from \"./Domain.ts\"\nimport * as internal from \"./internal/httpApi.ts\"\n\n/**\n * One check that an endpoint needs: an action on a kind of resource. With\n * `load`, the middleware loads the resource value from the path parameters\n * and checks the action on that value. Without `load`, it checks the action\n * on the kind.\n *\n * @stability unstable\n * @category models\n * @since 0.3.0\n */\nexport interface Requirement {\n\treadonly action: string\n\treadonly kind: string\n\treadonly load?: (\n\t\tparams: Readonly<Record<string, string | undefined>>,\n\t) => Effect.Effect<object, unknown, unknown>\n}\n\n/**\n * The checks that an endpoint needs.\n *\n * @stability unstable\n * @category annotations\n * @since 0.3.0\n */\nexport class Required extends Context.Service<\n\tRequired,\n\tReadonlyArray<Requirement>\n>()(\"@nmnmcc/ability/HttpApi/Required\") {}\n\n/**\n * The checks for every endpoint of a group with no {@link Required}\n * annotation. `read` is for GET requests. `write` is for all other methods.\n *\n * @stability unstable\n * @category annotations\n * @since 0.3.0\n */\nexport class GroupRequired extends Context.Service<\n\tGroupRequired,\n\t{\n\t\treadonly read: ReadonlyArray<Requirement>\n\t\treadonly write: ReadonlyArray<Requirement>\n\t}\n>()(\"@nmnmcc/ability/HttpApi/GroupRequired\") {}\n\n/**\n * Makes a {@link Requirement} with the types of an authorizer. The action must\n * be an action of the kind, and `load` must give a value of the kind.\n *\n * `load` may fail. Its errors must be errors of the middleware, and the\n * services that it needs must be given to {@link layer}.\n *\n * @stability unstable\n * @category constructors\n * @since 0.3.0\n */\nexport const requires: <\n\tA extends { readonly domain: Domain.Any },\n\tconst K extends Domain.Kind<A[\"domain\"]>,\n>(\n\tauthorizer: A,\n\taction: Domain.ActionOf<A[\"domain\"], K>,\n\tkind: K,\n\tload?: (\n\t\tparams: Readonly<Record<string, string | undefined>>,\n\t) => Effect.Effect<Domain.ValueOf<A[\"domain\"], K>, unknown, unknown>,\n) => Requirement = internal.requires\n\n/**\n * The errors of the middleware, with HTTP status codes: 403 for\n * `Forbidden`, 503 for `PolicyUnavailable`, and 409 for `Pending`.\n *\n * @stability unstable\n * @category errors\n * @since 0.3.0\n */\nexport const errors = [\n\tAuthorizer.Forbidden.pipe(HttpApiSchema.status(403)),\n\tAuthorizer.PolicyUnavailable.pipe(HttpApiSchema.status(503)),\n\tAuthorizer.Pending.pipe(HttpApiSchema.status(409)),\n] as const\n\n/**\n * Makes the layer of an authorization middleware. The middleware reads the\n * {@link Required} and {@link GroupRequired} annotations and checks each\n * requirement with the authorizer.\n *\n * The layer takes the authorizer when it is built. The middleware must\n * require the services of the authorizer, such as the identity of the\n * caller. `R` is the type of the services that the `load` functions need. The\n * layer takes them when it is built too.\n *\n * @stability unstable\n * @category layers\n * @since 0.3.0\n */\nexport const layer: <\n\tSelf,\n\tId extends string,\n\tA extends Authorizer.AnyServiceClass,\n\tR = never,\n>(\n\tmiddleware: Context.ServiceClass<Self, Id, any>,\n\tauthorizer: A,\n) => Layer.Layer<\n\tSelf,\n\tnever,\n\t(A extends Context.Key<infer I, any> ? I : never) | R\n> = internal.layer as never\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+DA,IAAa,WAAb,cAA8B,QAAQ,QAGpC,CAAC,CAAC,kCAAkC,CAAC,CAAC,CAAC;;;;;;;;;AAUzC,IAAa,gBAAb,cAAmC,QAAQ,QAMzC,CAAC,CAAC,uCAAuC,CAAC,CAAC,CAAC;;;;;;;;;;;;AAa9C,MAAa,WAUMA;;;;;;;;;AAUnB,MAAa,SAAS;CACA,UAAA,KAAK,cAAc,OAAO,GAAG,CAAC;CACtB,kBAAA,KAAK,cAAc,OAAO,GAAG,CAAC;CACxC,QAAA,KAAK,cAAc,OAAO,GAAG,CAAC;AAClD;;;;;;;;;;;;;;;AAgBA,MAAa,QAYTC"}
+{"version":3,"file":"HttpApi.js","names":["Authorizer.PolicyUnavailable","Resource.kindOf"],"sources":["../src/HttpApi.ts"],"sourcesContent":["/**\n * Tools to check authorization in an `effect/http-api` server.\n *\n * Each endpoint says what it needs with the {@link Required} annotation. A\n * group can give a default with {@link GroupRequired}: one list for GET\n * requests and one list for all other methods. A middleware checks the\n * requirements before the handler runs, in each group that uses it. An\n * endpoint with no annotation is a defect, so a new endpoint is closed until\n * you say what it needs. An empty list means the endpoint is open. An endpoint\n * in a group without the middleware is not checked at all.\n *\n * ```ts\n * class Authorization extends HttpApiMiddleware.Service<\n *   Authorization,\n *   { requires: Identity }\n * >()(\"app/Authorization\", { error: HttpApi.errors }) {}\n *\n * const endpoint = HttpApiEndpoint.patch(\"update\", \"/notes/:id\", { ... })\n *   .annotate(HttpApi.Required, [\n *     HttpApi.requires(Auth, \"update\", \"Note\", (params) => Notes.find(params.id)),\n *   ])\n *\n * const notes = HttpApiGroup.make(\"notes\").add(endpoint).middleware(Authorization)\n *\n * const AuthorizationLive = HttpApi.layer(Authorization, Auth)\n * ```\n *\n * This module is a separate entry point, `@nmnmcc/ability/HttpApi`, because\n * `effect/http-api` is not stable yet.\n *\n * @stability unstable\n * @since 0.3.0\n */\n// A `load` function of a requirement is kept in an annotation, so its error\n// type and its service type are erased to `unknown`. The language service\n// check for `unknown` in an Effect is off here.\n// @effect-diagnostics anyUnknownInErrorContext:off\nimport * as Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport * as Option from \"effect/Option\"\nimport * as Schema from \"effect/Schema\"\nimport * as SchemaTransformation from \"effect/SchemaTransformation\"\nimport { HttpRouter } from \"effect/http\"\nimport { HttpApiSchema } from \"effect/http-api\"\nimport * as Authorizer from \"./Authorizer.ts\"\nimport type * as Domain from \"./Domain.ts\"\nimport type * as Policy from \"./Policy.ts\"\nimport * as Resource from \"./Resource.ts\"\n\n/**\n * The path parameters of a request.\n *\n * @stability unstable\n * @category models\n * @since 1.0.0\n */\nexport type Params = Readonly<Record<string, string | undefined>>\n\n/**\n * One check that an endpoint needs: an action on a kind of resource.\n * - With `load`, the middleware loads the resource value from the path\n *   parameters and checks the action on that value.\n * - With `within`, it makes a scope from the path parameters and checks the\n *   action on every value in the scope.\n * - With `list`, the endpoint gives a list. The handler gets the list query\n *   with `Authorizer.filter`, so the middleware checks nothing, unless\n *   `nonEmpty` is true: then it fails when the principal may act on no value\n *   in the scope.\n * - With none of them, it checks the action on every value of the kind.\n *\n * @stability unstable\n * @category models\n * @since 0.3.0\n */\nexport interface Requirement {\n\treadonly action: string\n\treadonly kind: string\n\treadonly load?: (params: Params) => Effect.Effect<object, unknown, unknown>\n\treadonly within?: (params: Params) => unknown\n\treadonly list?: { readonly nonEmpty: boolean }\n}\n\n/**\n * The checks that an endpoint needs.\n *\n * @stability unstable\n * @category annotations\n * @since 0.3.0\n */\nexport class Required extends Context.Service<\n\tRequired,\n\tReadonlyArray<Requirement>\n>()(\"@nmnmcc/ability/HttpApi/Required\") {}\n\n/**\n * The checks for every endpoint of a group with no {@link Required}\n * annotation. `read` is for GET requests. `write` is for all other methods.\n *\n * @stability unstable\n * @category annotations\n * @since 0.3.0\n */\nexport class GroupRequired extends Context.Service<\n\tGroupRequired,\n\t{\n\t\treadonly read: ReadonlyArray<Requirement>\n\t\treadonly write: ReadonlyArray<Requirement>\n\t}\n>()(\"@nmnmcc/ability/HttpApi/GroupRequired\") {}\n\n/**\n * Makes a {@link Requirement} with the types of an authorizer. The action must\n * be an action of the kind, also when the kind has a union type.\n *\n * The last argument is one of:\n * - a `load` function, which must give a value of the kind. It may fail. Its\n *   errors must be errors of the middleware, and the services that it needs\n *   must be given to {@link layer}.\n * - `{ within }`, a function from the path parameters to a scope. Use it for\n *   an act on a part of the kind, such as a new value with no id yet:\n *   `{ within: (params) => ($) => $.under(\"org\", params.org ?? null) }`. A path\n *   parameter may be `undefined`, and a scope with `undefined` in it is a\n *   defect, so give a value for it.\n *\n * @stability unstable\n * @category constructors\n * @since 0.3.0\n */\nexport const requires: <\n\tA extends { readonly domain: Domain.Any },\n\tconst K extends Domain.Kind<A[\"domain\"]>,\n>(\n\tauthorizer: A,\n\taction: Domain.CommonAction<A[\"domain\"], K>,\n\tkind: K,\n\thow?:\n\t\t| ((\n\t\t\t\tparams: Params,\n\t\t  ) => Effect.Effect<Domain.ValueOf<A[\"domain\"], K>, unknown, unknown>)\n\t\t| { readonly within: (params: Params) => Policy.Scope<A[\"domain\"], K> },\n) => Requirement = (_authorizer, action, kind, how) =>\n\thow === undefined\n\t\t? { action: action as string, kind }\n\t\t: typeof how === \"function\"\n\t\t\t? { action: action as string, kind, load: how }\n\t\t\t: { action: action as string, kind, within: how.within }\n\n/**\n * Makes a {@link Requirement} for an endpoint that gives a list. The middleware\n * does not check that the principal may act on every value, because the list\n * shows only the values that it may act on. The handler gets the list query\n * with `Authorizer.filter`, with the same scope.\n *\n * When the principal may act on no value, the list is empty: that is not an\n * error, so a client does not learn that hidden values are there. With\n * `nonEmpty: true`, the middleware fails with `Forbidden` in that case. It\n * also fails when the coverage is `Unknown`, because then it can not say that\n * the list has a value.\n *\n * @stability unstable\n * @category constructors\n * @since 1.0.0\n */\nexport const lists: <\n\tA extends { readonly domain: Domain.Any },\n\tconst K extends Domain.Kind<A[\"domain\"]>,\n>(\n\tauthorizer: A,\n\taction: Domain.CommonAction<A[\"domain\"], K>,\n\tkind: K,\n\toptions?: {\n\t\treadonly within?: (params: Params) => Policy.Scope<A[\"domain\"], K>\n\t\treadonly nonEmpty?: boolean\n\t},\n) => Requirement = (_authorizer, action, kind, options) => ({\n\taction: action as string,\n\tkind,\n\tlist: { nonEmpty: options?.nonEmpty ?? false },\n\t...(options?.within === undefined ? {} : { within: options.within }),\n})\n\n/**\n * The Schema of a `PolicyUnavailable` response. It encodes only the `_tag`, so\n * the cause does not go to the client.\n */\nconst PolicyUnavailableResponse = Schema.TaggedStruct(\n\t\"PolicyUnavailable\",\n\t{},\n).pipe(\n\tSchema.decodeTo(\n\t\tSchema.declare(\n\t\t\t(u): u is Authorizer.PolicyUnavailable =>\n\t\t\t\tu instanceof Authorizer.PolicyUnavailable,\n\t\t),\n\t\tSchemaTransformation.transform({\n\t\t\tdecode: () => Authorizer.PolicyUnavailable.make({ cause: undefined }),\n\t\t\tencode: () => ({ _tag: \"PolicyUnavailable\" as const }),\n\t\t}),\n\t),\n)\n\n/**\n * The errors of the middleware, with HTTP status codes: 403 for\n * `Forbidden`, 503 for `PolicyUnavailable`, and 409 for `Pending`.\n *\n * The body of a `PolicyUnavailable` response has only its `_tag`. The cause\n * may have private details, such as an error from the database, so it stays\n * on the server.\n *\n * @stability unstable\n * @category errors\n * @since 0.3.0\n */\nexport const errors = [\n\tAuthorizer.Forbidden.pipe(HttpApiSchema.status(403)),\n\tPolicyUnavailableResponse.pipe(HttpApiSchema.status(503)),\n\tAuthorizer.Pending.pipe(HttpApiSchema.status(409)),\n] as const\n\nconst makeLayer = (\n\tmiddleware: Context.ServiceClass<any, string, any>,\n\tauthorizer: Authorizer.AnyServiceClass,\n) =>\n\tLayer.effect(\n\t\tmiddleware,\n\t\tEffect.gen(function* () {\n\t\t\tconst service = yield* authorizer\n\t\t\tconst services = yield* Effect.context<never>()\n\t\t\treturn Effect.fnUntraced(function* (\n\t\t\t\thttpEffect: Effect.Effect<unknown, unknown, unknown>,\n\t\t\t\toptions: {\n\t\t\t\t\treadonly endpoint: {\n\t\t\t\t\t\treadonly name: string\n\t\t\t\t\t\treadonly method: string\n\t\t\t\t\t\treadonly annotations: Context.Context<never>\n\t\t\t\t\t}\n\t\t\t\t\treadonly group: {\n\t\t\t\t\t\treadonly identifier: string\n\t\t\t\t\t\treadonly annotations: Context.Context<never>\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t) {\n\t\t\t\tconst requirements = Option.orElse(\n\t\t\t\t\tContext.getOption(options.endpoint.annotations, Required),\n\t\t\t\t\t() =>\n\t\t\t\t\t\tOption.map(\n\t\t\t\t\t\t\tContext.getOption(options.group.annotations, GroupRequired),\n\t\t\t\t\t\t\t(rules) =>\n\t\t\t\t\t\t\t\toptions.endpoint.method === \"GET\" ? rules.read : rules.write,\n\t\t\t\t\t\t),\n\t\t\t\t)\n\t\t\t\tif (Option.isNone(requirements)) {\n\t\t\t\t\treturn yield* Effect.die(\n\t\t\t\t\t\tnew Error(\n\t\t\t\t\t\t\t`The endpoint ${options.group.identifier}.${options.endpoint.name} does not say what it needs. Give it the HttpApi.Required annotation.`,\n\t\t\t\t\t\t),\n\t\t\t\t\t)\n\t\t\t\t}\n\t\t\t\tconst endpoint = `${options.group.identifier}.${options.endpoint.name}`\n\t\t\t\t// The requirements are checked in order. The first one that fails\n\t\t\t\t// stops the request.\n\t\t\t\tyield* Effect.forEach(\n\t\t\t\t\trequirements.value,\n\t\t\t\t\t({ action, kind, load, within, list }) => {\n\t\t\t\t\t\tif (load !== undefined) {\n\t\t\t\t\t\t\treturn HttpRouter.params.pipe(\n\t\t\t\t\t\t\t\tEffect.flatMap((params) =>\n\t\t\t\t\t\t\t\t\tEffect.provideContext(load(params), services),\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t\t// The check is for the kind of the requirement. A value of\n\t\t\t\t\t\t\t\t// another kind is a mistake in `load`, and the check must\n\t\t\t\t\t\t\t\t// not pass with the rules of that other kind.\n\t\t\t\t\t\t\t\tEffect.filterOrElse(\n\t\t\t\t\t\t\t\t\t(value) => Resource.kindOf(value) === kind,\n\t\t\t\t\t\t\t\t\t() =>\n\t\t\t\t\t\t\t\t\t\tEffect.die(\n\t\t\t\t\t\t\t\t\t\t\tnew Error(\n\t\t\t\t\t\t\t\t\t\t\t\t`The load function of ${endpoint} gave a value that is not a ${kind}`,\n\t\t\t\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t\tEffect.flatMap((value) =>\n\t\t\t\t\t\t\t\t\tservice.check({ action, resource: value } as never),\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t}\n\t\t\t\t\t\tconst target =\n\t\t\t\t\t\t\twithin === undefined\n\t\t\t\t\t\t\t\t? Effect.succeed({ action, kind } as never)\n\t\t\t\t\t\t\t\t: Effect.map(\n\t\t\t\t\t\t\t\t\t\tHttpRouter.params,\n\t\t\t\t\t\t\t\t\t\t(params) =>\n\t\t\t\t\t\t\t\t\t\t\t({ action, kind, within: within(params) }) as never,\n\t\t\t\t\t\t\t\t\t)\n\t\t\t\t\t\tif (list === undefined) {\n\t\t\t\t\t\t\treturn Effect.flatMap(target, (value) => service.check(value))\n\t\t\t\t\t\t}\n\t\t\t\t\t\t// A list endpoint may give an empty list, unless it must not.\n\t\t\t\t\t\t// Only `All` and `Some` say that the list has a value. `Unknown`\n\t\t\t\t\t\t// is not a \"yes\".\n\t\t\t\t\t\treturn list.nonEmpty\n\t\t\t\t\t\t\t? target.pipe(\n\t\t\t\t\t\t\t\t\tEffect.flatMap((value) => service.coverage(value)),\n\t\t\t\t\t\t\t\t\tEffect.filterOrElse(\n\t\t\t\t\t\t\t\t\t\t(covered) =>\n\t\t\t\t\t\t\t\t\t\t\t(covered as { readonly _tag: string })._tag === \"All\" ||\n\t\t\t\t\t\t\t\t\t\t\t(covered as { readonly _tag: string })._tag === \"Some\",\n\t\t\t\t\t\t\t\t\t\t() =>\n\t\t\t\t\t\t\t\t\t\t\tEffect.fail(Authorizer.Forbidden.make({ action, kind })),\n\t\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t\t)\n\t\t\t\t\t\t\t: Effect.void\n\t\t\t\t\t},\n\t\t\t\t\t{ discard: true },\n\t\t\t\t)\n\t\t\t\treturn yield* httpEffect\n\t\t\t})\n\t\t}),\n\t)\n\n/**\n * Makes the layer of an authorization middleware. The middleware reads the\n * {@link Required} and {@link GroupRequired} annotations and checks each\n * requirement with the authorizer.\n *\n * The layer takes the authorizer when it is built. The middleware must\n * require the services of the authorizer, such as the identity of the\n * caller. `R` is the type of the services that the `load` functions need. The\n * layer takes them when it is built too.\n *\n * @stability unstable\n * @category layers\n * @since 0.3.0\n */\nexport const layer: <\n\tSelf,\n\tId extends string,\n\tA extends Authorizer.AnyServiceClass,\n\tR = never,\n>(\n\tmiddleware: Context.ServiceClass<Self, Id, any>,\n\tauthorizer: A,\n) => Layer.Layer<\n\tSelf,\n\tnever,\n\t(A extends Context.Key<infer I, any> ? I : never) | R\n> = makeLayer as never\n"],"mappings":"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"}