@nmnmcc/ability 0.3.0 → 1.0.1

package/src/Domain.ts

@@ -8,30 +8,19 @@
  * ```ts
  * import { Domain } from "@nmnmcc/ability"
  *
- * const App = Domain.make({ principal: Caller, resources: [Bot, Trigger] })
+ * const App = Domain.make({ principal: Member, resources: [Document, Comment] })
  * ```
  *
  * @stability stable
  * @since 0.3.0
  */
+import * as Arr from "effect/Array"
+import * as Data from "effect/Data"
+import * as HashMap from "effect/HashMap"
+import * as Option from "effect/Option"
 import type * as Schema from "effect/Schema"
-import * as internal from "./internal/domain.ts"
 import type * as PrincipalSchema from "./Principal.ts"
-import type * as Resource from "./Resource.ts"
-
-/**
- * @stability stable
- * @category type IDs
- * @since 0.3.0
- */
-export const TypeId: "~@nmnmcc/ability/Domain" = internal.TypeId
-
-/**
- * @stability stable
- * @category type IDs
- * @since 0.3.0
- */
-export type TypeId = typeof TypeId
+import * as Resource from "./Resource.ts"
 
 /**
  * A domain. `P` is the type of the principal, `Resources` is the union of the
@@ -46,9 +35,9 @@ export interface Domain<
 	Resources extends Resource.Any,
 	Meta,
 > {
-	readonly [TypeId]: TypeId
 	readonly principal: PrincipalSchema.Any
-	readonly resources: ReadonlyMap<string, Resource.Descriptor>
+	/** The descriptor of each resource, by its kind name. */
+	readonly resources: HashMap.HashMap<string, Resource.Descriptor>
 	readonly meta: Schema.Top | undefined
 	readonly "~Domain"?: {
 		readonly Principal: P
@@ -125,6 +114,21 @@ export type ResourceOf<D, K extends string> =
  */
 export type ActionOf<D, K extends string> = Resource.Action<ResourceOf<D, K>>
 
+/**
+ * The actions that every kind in `K` has. For one kind, they are its actions.
+ * For a union of kinds, an action of only some of them is left out, so a
+ * value of the union type can not get an action that its kind does not have.
+ *
+ * @stability stable
+ * @category utility types
+ * @since 1.0.0
+ */
+export type CommonAction<D, K extends string> = (
+	K extends unknown ? (action: ActionOf<D, K>) => void : never
+) extends (action: infer A) => void
+	? A
+	: never
+
 /**
  * All the actions of all the resources of a domain.
  *
@@ -161,9 +165,20 @@ export type ValueOf<D, K extends string> = Resource.Value<ResourceOf<D, K>>
  */
 export type AnyValue<D> = Resource.Value<Resources<D>>
 
+/**
+ * The class of every domain value. {@link isDomain} uses it to know a domain.
+ */
+class DomainData extends Data.Class<{
+	readonly principal: PrincipalSchema.Any
+	readonly resources: HashMap.HashMap<string, Resource.Descriptor>
+	readonly meta: Schema.Top | undefined
+}> {}
+
 /**
  * Makes a domain. Each resource must have its own kind name. Give `meta` when
- * rules must keep extra data, such as the scope of a grant.
+ * rules must keep extra data, such as the scope of a grant. The `meta` Schema
+ * may not need services, because `Policy.schema` gives a Schema that needs
+ * none.
  *
  * @stability stable
  * @category constructors
@@ -172,12 +187,54 @@ export type AnyValue<D> = Resource.Value<Resources<D>>
 export const make: <
 	P extends PrincipalSchema.Any,
 	const Resources extends ReadonlyArray<Resource.Any>,
-	M extends Schema.Top = Schema.Never,
+	M extends Schema.Codec<any, any, never, never> = Schema.Never,
 >(options: {
 	readonly principal: P
 	readonly resources: Resources
 	readonly meta?: M
-}) => Domain<P["Type"], Resources[number], M["Type"]> = internal.make
+}) => Domain<P["Type"], Resources[number], M["Type"]> = (options) => {
+	const descriptors = Arr.map(options.resources, Resource.descriptor)
+	const kinds = Arr.map(descriptors, (descriptor) => descriptor.kind)
+	// Two resources with one kind name is a mistake in the code, not in the
+	// data, so it is a defect.
+	const twice = Arr.findFirst(
+		kinds,
+		(kind, index) => kinds.indexOf(kind) !== index,
+	)
+	if (Option.isSome(twice)) {
+		throw new Error(`Two resources have the kind name "${twice.value}"`)
+	}
+	if (kinds.includes("*")) {
+		throw new Error(`A resource may not have the kind name "*"`)
+	}
+	const resources = HashMap.fromIterable(
+		Arr.map(
+			descriptors,
+			(descriptor) => [descriptor.kind, descriptor] as const,
+		),
+	)
+	// This checks the field names of the principal. See `Resource.fieldPaths`.
+	Resource.fieldPaths(options.principal)
+	return new DomainData({
+		principal: options.principal,
+		resources,
+		meta: options.meta,
+	})
+}
+
+/**
+ * Gives the descriptor of the resource with a kind name, or `undefined` when
+ * the domain has no such resource.
+ *
+ * @stability stable
+ * @category getters
+ * @since 1.0.0
+ */
+export const descriptorOf = (
+	domain: Any,
+	kind: string,
+): Resource.Descriptor | undefined =>
+	Option.getOrUndefined(HashMap.get(domain.resources, kind))
 
 /**
  * Tests if a value is a domain.
@@ -186,4 +243,4 @@ export const make: <
  * @category guards
  * @since 0.3.0
  */
-export const isDomain: (u: unknown) => u is Any = internal.isDomain
+export const isDomain = (u: unknown): u is Any => u instanceof DomainData

package/src/HttpApi.ts

@@ -4,9 +4,10 @@
  * 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<
@@ -14,11 +15,13 @@
  *   { 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)
  * ```
  *
@@ -28,19 +31,43 @@
  * @stability unstable
  * @since 0.3.0
  */
+// A `load` function of a requirement is kept in an annotation, so its error
+// type and its service type are erased to `unknown`. The language service
+// check for `unknown` in an Effect is off here.
+// @effect-diagnostics anyUnknownInErrorContext:off
 import * as Context from "effect/Context"
-import type * as Effect from "effect/Effect"
-import type * as Layer from "effect/Layer"
+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"
 import * as Authorizer from "./Authorizer.ts"
 import type * as Domain from "./Domain.ts"
-import * as internal from "./internal/httpApi.ts"
+import type * as Policy from "./Policy.ts"
+import * as Resource from "./Resource.ts"
+
+/**
+ * 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. Without `load`, it checks the action
- * on the kind.
+ * 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
@@ -49,9 +76,9 @@ import * as internal from "./internal/httpApi.ts"
 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 }
 }
 
 /**
@@ -84,10 +111,17 @@ export class GroupRequired extends Context.Service<
 
 /**
  * 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
@@ -98,27 +132,193 @@ export const requires: <
 	const K extends Domain.Kind<A["domain"]>,
 >(
 	authorizer: A,
-	action: Domain.ActionOf<A["domain"], K>,
+	action: Domain.CommonAction<A["domain"], K>,
+	kind: K,
+	how?:
+		| ((
+				params: Params,
+		  ) => Effect.Effect<Domain.ValueOf<A["domain"], K>, unknown, unknown>)
+		| { readonly within: (params: Params) => Policy.Scope<A["domain"], K> },
+) => Requirement = (_authorizer, action, kind, how) =>
+	how === undefined
+		? { action: action as string, kind }
+		: typeof how === "function"
+			? { action: action as string, kind, load: how }
+			: { action: action as string, 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
+ */
+export const lists: <
+	A extends { readonly domain: Domain.Any },
+	const K extends Domain.Kind<A["domain"]>,
+>(
+	authorizer: A,
+	action: Domain.CommonAction<A["domain"], K>,
 	kind: K,
-	load?: (
-		params: Readonly<Record<string, string | undefined>>,
-	) => Effect.Effect<Domain.ValueOf<A["domain"], K>, unknown, unknown>,
-) => Requirement = internal.requires
+	options?: {
+		readonly within?: (params: Params) => Policy.Scope<A["domain"], K>
+		readonly nonEmpty?: boolean
+	},
+) => Requirement = (_authorizer, action, kind, options) => ({
+	action: action as string,
+	kind,
+	list: { nonEmpty: options?.nonEmpty ?? false },
+	...(options?.within === undefined ? {} : { 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 is Authorizer.PolicyUnavailable =>
+				u instanceof Authorizer.PolicyUnavailable,
+		),
+		SchemaTransformation.transform({
+			decode: () => Authorizer.PolicyUnavailable.make({ cause: undefined }),
+			encode: () => ({ _tag: "PolicyUnavailable" as const }),
+		}),
+	),
+)
 
 /**
  * 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 const errors = [
 	Authorizer.Forbidden.pipe(HttpApiSchema.status(403)),
-	Authorizer.PolicyUnavailable.pipe(HttpApiSchema.status(503)),
+	PolicyUnavailableResponse.pipe(HttpApiSchema.status(503)),
 	Authorizer.Pending.pipe(HttpApiSchema.status(409)),
 ] as const
 
+const makeLayer = (
+	middleware: Context.ServiceClass<any, string, any>,
+	authorizer: Authorizer.AnyServiceClass,
+) =>
+	Layer.effect(
+		middleware,
+		Effect.gen(function* () {
+			const service = yield* authorizer
+			const services = yield* Effect.context<never>()
+			return Effect.fnUntraced(function* (
+				httpEffect: Effect.Effect<unknown, unknown, unknown>,
+				options: {
+					readonly endpoint: {
+						readonly name: string
+						readonly method: string
+						readonly annotations: Context.Context<never>
+					}
+					readonly group: {
+						readonly identifier: string
+						readonly annotations: Context.Context<never>
+					}
+				},
+			) {
+				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(
+						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}`
+				// The requirements are checked in order. The first one that fails
+				// stops the request.
+				yield* Effect.forEach(
+					requirements.value,
+					({ action, kind, load, within, list }) => {
+						if (load !== undefined) {
+							return HttpRouter.params.pipe(
+								Effect.flatMap((params) =>
+									Effect.provideContext(load(params), services),
+								),
+								// The check is for the kind of the requirement. A value of
+								// another kind is a mistake in `load`, and the check must
+								// not pass with the rules of that other kind.
+								Effect.filterOrElse(
+									(value) => Resource.kindOf(value) === kind,
+									() =>
+										Effect.die(
+											new Error(
+												`The load function of ${endpoint} gave a value that is not a ${kind}`,
+											),
+										),
+								),
+								Effect.flatMap((value) =>
+									service.check({ action, resource: value } as never),
+								),
+							)
+						}
+						const target =
+							within === undefined
+								? Effect.succeed({ action, kind } as never)
+								: Effect.map(
+										HttpRouter.params,
+										(params) =>
+											({ action, kind, within: within(params) }) as never,
+									)
+						if (list === undefined) {
+							return Effect.flatMap(target, (value) => service.check(value))
+						}
+						// A list endpoint may give an empty list, unless it must not.
+						// Only `All` and `Some` say that the list has a value. `Unknown`
+						// is not a "yes".
+						return list.nonEmpty
+							? target.pipe(
+									Effect.flatMap((value) => service.coverage(value)),
+									Effect.filterOrElse(
+										(covered) =>
+											(covered as { readonly _tag: string })._tag === "All" ||
+											(covered as { readonly _tag: string })._tag === "Some",
+										() =>
+											Effect.fail(Authorizer.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
@@ -145,4 +345,4 @@ export const layer: <
 	Self,
 	never,
 	(A extends Context.Key<infer I, any> ? I : never) | R
-> = internal.layer as never
+> = makeLayer as never