@nmnmcc/ability 1.0.1 → 2.0.1

package/src/Decision.ts

@@ -12,7 +12,7 @@
  * @since 0.3.0
  */
 import * as Data from "effect/Data"
-import type * as Rule from "./Rule.ts"
+import type * as Policy from "./Policy.ts"
 
 /**
  * @stability stable
@@ -22,11 +22,11 @@ import type * as Rule from "./Rule.ts"
 export type Decision = Data.TaggedEnum<{
 	Allow: {
 		/** The rule that gave the answer, when a rule gave it. */
-		readonly rule?: Rule.Any
+		readonly rule?: Policy.AnyRule
 	}
 	Deny: {
 		/** The rule that gave the answer, when a rule gave it. */
-		readonly rule?: Rule.Any
+		readonly rule?: Policy.AnyRule
 		readonly reason?: string
 	}
 	NotApplicable: {}
@@ -45,7 +45,8 @@ const {
  * @category constructors
  * @since 0.3.0
  */
-export const Allow: (args: { readonly rule?: Rule.Any }) => Decision = allow
+export const Allow: (args: { readonly rule?: Policy.AnyRule }) => Decision =
+	allow
 
 /**
  * @stability stable
@@ -53,7 +54,7 @@ export const Allow: (args: { readonly rule?: Rule.Any }) => Decision = allow
  * @since 0.3.0
  */
 export const Deny: (args: {
-	readonly rule?: Rule.Any
+	readonly rule?: Policy.AnyRule
 	readonly reason?: string
 }) => Decision = deny
 

package/src/Domain.ts

@@ -14,13 +14,14 @@
  * @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 HashMap from "effect/HashMap"
 import type * as Schema from "effect/Schema"
-import type * as PrincipalSchema from "./Principal.ts"
-import * as Resource from "./Resource.ts"
+import type * as Catalog from "./internal/catalog.ts"
+import * as Internal from "./internal/domain.ts"
+import type * as Resource from "./Resource.ts"
+
+/** The Schema of a principal: a Schema of objects, such as a `Schema.Class`. */
+type PrincipalSchema = Schema.Top & { readonly Type: object }
 
 /**
  * A domain. `P` is the type of the principal, `Resources` is the union of the
@@ -35,7 +36,9 @@ export interface Domain<
 	Resources extends Resource.Any,
 	Meta,
 > {
-	readonly principal: PrincipalSchema.Any
+	readonly principal: PrincipalSchema
+	/** The catalog of the data fields of the principal. */
+	readonly principalCatalog: Catalog.Catalog
 	/** The descriptor of each resource, by its kind name. */
 	readonly resources: HashMap.HashMap<string, Resource.Descriptor>
 	readonly meta: Schema.Top | undefined
@@ -165,15 +168,6 @@ 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. The `meta` Schema
@@ -185,62 +179,11 @@ class DomainData extends Data.Class<{
  * @since 0.3.0
  */
 export const make: <
-	P extends PrincipalSchema.Any,
+	P extends PrincipalSchema,
 	const Resources extends ReadonlyArray<Resource.Any>,
 	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"]> = (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.
- *
- * @stability stable
- * @category guards
- * @since 0.3.0
- */
-export const isDomain = (u: unknown): u is Any => u instanceof DomainData
+}) => Domain<P["Type"], Resources[number], M["Type"]> = Internal.make as never

package/src/HttpApi.ts

@@ -44,9 +44,10 @@ 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 Condition from "./Condition.ts"
 import type * as Domain from "./Domain.ts"
 import type * as Policy from "./Policy.ts"
-import * as Resource from "./Resource.ts"
+import * as ResourceData from "./internal/resource.ts"
 
 /**
  * The path parameters of a request.
@@ -146,11 +147,49 @@ export const requires: <
 			? { action: action as string, kind, load: how }
 			: { action: action as string, kind, within: how.within }
 
+/**
+ * A {@link Requirement} for an endpoint that gives a list, with the list query
+ * for the handler. `filter` takes the authorizer, which the handler gets when
+ * its group is built. It reads the path parameters of the request, and it
+ * gives the condition of `Authorizer.filter` in the scope of the requirement.
+ * So the scope is written one time, for the middleware and for the handler.
+ *
+ * @stability unstable
+ * @category models
+ * @since 2.0.0
+ */
+export interface List<A, K extends string> extends Requirement {
+	readonly filter: A extends Authorizer.ServiceClass<
+		any,
+		any,
+		infer D,
+		infer E,
+		infer R
+	>
+		? (
+				authorizer: Authorizer.Authorizer<D, E, R>,
+			) => Effect.Effect<
+				Condition.Condition<Policy.ResidualReads<D, K>, Condition.Opaque<E>>,
+				Authorizer.PolicyUnavailable | E,
+				R | HttpRouter.RouteContext
+			>
+		: never
+}
+
 /**
  * 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.
+ * from `filter` of the result, with the same scope:
+ *
+ * ```ts
+ * const byAuthor = HttpApi.lists(Auth, "read", "Note", {
+ *   within: (params) => ($) => $.eq("authorId", params.user ?? null),
+ * })
+ * // When the group is built: const auth = yield* Auth
+ * // In the handler:
+ * const where = yield* byAuthor.filter(auth)
+ * ```
  *
  * 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
@@ -163,7 +202,7 @@ export const requires: <
  * @since 1.0.0
  */
 export const lists: <
-	A extends { readonly domain: Domain.Any },
+	A extends Authorizer.AnyServiceClass,
 	const K extends Domain.Kind<A["domain"]>,
 >(
 	authorizer: A,
@@ -173,12 +212,35 @@ export const lists: <
 		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 }),
-})
+) => List<A, K> = ((
+	_authorizer: Authorizer.AnyServiceClass,
+	action: string,
+	kind: string,
+	options?: {
+		readonly within?: (params: Params) => unknown
+		readonly nonEmpty?: boolean
+	},
+) => {
+	const within = options?.within
+	return {
+		action,
+		kind,
+		list: { nonEmpty: options?.nonEmpty ?? false },
+		...(within === undefined ? {} : { within }),
+		filter: (authorizer: {
+			readonly filter: (
+				target: object,
+			) => Effect.Effect<unknown, unknown, unknown>
+		}) =>
+			Effect.flatMap(HttpRouter.params, (params) =>
+				authorizer.filter({
+					action,
+					kind,
+					...(within === undefined ? {} : { within: within(params) }),
+				}),
+			),
+	}
+}) as never
 
 /**
  * The Schema of a `PolicyUnavailable` response. It encodes only the `_tag`, so
@@ -272,7 +334,7 @@ const makeLayer = (
 								// 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,
+									(value) => ResourceData.kindOf(value) === kind,
 									() =>
 										Effect.die(
 											new Error(

package/src/Limits.ts

@@ -0,0 +1,132 @@
+/**
+ * The limits of the library. Each one keeps a walk, a decoder or a search
+ * small, so no input can fill the stack or take a very long time. An input
+ * past a limit is an error, with one form of message, as in "A condition has
+ * 100001 nodes. The most is 100000.". In an `Authorizer`, such an error is
+ * never a "yes".
+ *
+ * @stability stable
+ * @since 2.0.0
+ */
+import * as Limits from "./internal/limits.ts"
+
+/**
+ * The most parts of a field path, as in `settings.model`. The types of the
+ * field paths go to the same depth.
+ *
+ * @stability stable
+ * @category constants
+ * @since 2.0.0
+ */
+export const fieldPathParts: number = Limits.fieldPathParts
+
+/**
+ * The most parts of a field pattern, as in `**.secret`.
+ *
+ * @stability stable
+ * @category constants
+ * @since 2.0.0
+ */
+export const patternParts: number = Limits.patternParts
+
+/**
+ * The most nodes of one condition. A part that a condition uses in many
+ * places counts for each place.
+ *
+ * @stability stable
+ * @category constants
+ * @since 2.0.0
+ */
+export const conditionNodes: number = Limits.conditionNodes
+
+/**
+ * The most levels of one condition.
+ *
+ * @stability stable
+ * @category constants
+ * @since 2.0.0
+ */
+export const conditionDepth: number = Limits.conditionDepth
+
+/**
+ * The most nodes of one residual condition.
+ *
+ * @stability stable
+ * @category constants
+ * @since 2.0.0
+ */
+export const residualNodes: number = Limits.residualNodes
+
+/**
+ * The most levels of a policy tree.
+ *
+ * @stability stable
+ * @category constants
+ * @since 2.0.0
+ */
+export const policyDepth: number = Limits.policyDepth
+
+/**
+ * The most nodes of a policy tree, with its rules and the nodes of their
+ * conditions. A part that the tree uses in many places counts for each place.
+ *
+ * @stability stable
+ * @category constants
+ * @since 2.0.0
+ */
+export const policyNodes: number = Limits.policyNodes
+
+/**
+ * The most objects and arrays in one input to the Schema of a policy or of a
+ * condition.
+ *
+ * @stability stable
+ * @category constants
+ * @since 2.0.0
+ */
+export const jsonNodes: number = Limits.jsonNodes
+
+/**
+ * The most fields in the catalog of one Schema.
+ *
+ * @stability stable
+ * @category constants
+ * @since 2.0.0
+ */
+export const catalogFields: number = Limits.catalogFields
+
+/**
+ * The most steps of one search for a value, as in `Policy.coverage`. Past
+ * it, the answer is `Unknown`.
+ *
+ * @stability stable
+ * @category constants
+ * @since 2.0.0
+ */
+export const searchSteps: number = Limits.searchSteps
+
+/**
+ * The most fields that one search for a value may test. Past it, the answer
+ * is `Unknown`.
+ *
+ * @stability stable
+ * @category constants
+ * @since 2.0.0
+ */
+export const searchFields: number = Limits.searchFields
+
+/**
+ * The error when an input goes past a limit.
+ *
+ * @stability stable
+ * @category errors
+ * @since 2.0.0
+ */
+export const LimitExceeded: typeof Limits.LimitExceeded = Limits.LimitExceeded
+
+/**
+ * @stability stable
+ * @category errors
+ * @since 2.0.0
+ */
+export type LimitExceeded = Limits.LimitExceeded