@nmnmcc/ability 2.0.7 → 2.1.2

package/src/Limits.ts

@@ -1,24 +1,56 @@
 /**
- * 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
+ * The limits of the library. Each one keeps a decoder, a walk or a search
+ * small, so no input can take a very long time or very much memory. 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".
+ * 1000001 nodes and values. The most is 1000000.". In an `Authorizer`, such
+ * an error is never a "yes".
+ *
+ * The constants here are the defaults. A domain may set its own limits, up
+ * to the {@link ceilings}: see `Domain.make`. A walk does not fill the stack
+ * at any depth, and the levels of an input are at most its nodes, so there is
+ * no limit of levels.
  *
  * @stability stable
  * @since 2.0.0
  */
-import * as Limits from "./internal/limits.ts"
+import * as Internal from "./internal/limits.ts"
+
+/**
+ * The values of all the limits.
+ *
+ * @stability stable
+ * @category models
+ * @since 2.1.0
+ */
+export type Limits = Internal.Limits
+
+/**
+ * The limits of a domain that sets none.
+ *
+ * @stability stable
+ * @category constants
+ * @since 2.1.0
+ */
+export const defaults: Limits = Internal.defaults
+
+/**
+ * The most that a domain may set for each limit.
+ *
+ * @stability stable
+ * @category constants
+ * @since 2.1.0
+ */
+export const ceilings: Limits = Internal.ceilings
 
 /**
- * The most parts of a field path, as in `settings.model`. The types of the
- * field paths go to the same depth.
+ * The most parts of a field path, as in `settings.model`, by default. The
+ * types check a path that you write up to about 1000 parts.
  *
  * @stability stable
  * @category constants
  * @since 2.0.0
  */
-export const fieldPathParts: number = Limits.fieldPathParts
+export const fieldPathParts: number = Internal.fieldPathParts
 
 /**
  * The most parts of a field pattern, as in `**.secret`.
@@ -27,26 +59,29 @@ export const fieldPathParts: number = Limits.fieldPathParts
  * @category constants
  * @since 2.0.0
  */
-export const patternParts: number = Limits.patternParts
+export const patternParts: number = Internal.patternParts
 
 /**
- * The most nodes of one condition. A part that a condition uses in many
- * places counts for each place.
+ * The most nodes of one condition, with each value of an `In` or `Under`
+ * test. 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
+export const conditionNodes: number = Internal.conditionNodes
 
 /**
- * The most levels of one condition.
+ * There is no limit of the levels of a condition: a walk does not fill the
+ * stack, and the levels are at most the nodes, which `conditionNodes`
+ * limits.
  *
- * @stability stable
+ * @deprecated Since 2.1.0, there is no such limit. The value is `Infinity`.
+ * @stability deprecated
  * @category constants
  * @since 2.0.0
  */
-export const conditionDepth: number = Limits.conditionDepth
+export const conditionDepth: number = Number.POSITIVE_INFINITY
 
 /**
  * The most nodes of one residual condition.
@@ -55,26 +90,29 @@ export const conditionDepth: number = Limits.conditionDepth
  * @category constants
  * @since 2.0.0
  */
-export const residualNodes: number = Limits.residualNodes
+export const residualNodes: number = Internal.residualNodes
 
 /**
- * The most levels of a policy tree.
+ * There is no limit of the levels of a policy tree: a walk does not fill the
+ * stack, and the levels are at most the nodes, which `policyNodes` limits.
  *
- * @stability stable
+ * @deprecated Since 2.1.0, there is no such limit. The value is `Infinity`.
+ * @stability deprecated
  * @category constants
  * @since 2.0.0
  */
-export const policyDepth: number = Limits.policyDepth
+export const policyDepth: number = Number.POSITIVE_INFINITY
 
 /**
- * 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.
+ * The most nodes of a policy tree, with its rules and the nodes and values
+ * 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
+export const policyNodes: number = Internal.policyNodes
 
 /**
  * The most objects and arrays in one input to the Schema of a policy or of a
@@ -84,16 +122,17 @@ export const policyNodes: number = Limits.policyNodes
  * @category constants
  * @since 2.0.0
  */
-export const jsonNodes: number = Limits.jsonNodes
+export const jsonNodes: number = Internal.jsonNodes
 
 /**
- * The most fields in the catalog of one Schema.
+ * The most fields in the list of the fields of one Schema, as
+ * `Policy.permittedFields` reads it.
  *
  * @stability stable
  * @category constants
  * @since 2.0.0
  */
-export const catalogFields: number = Limits.catalogFields
+export const catalogFields: number = Internal.catalogFields
 
 /**
  * The most steps of one search for a value, as in `Policy.coverage`. Past
@@ -105,7 +144,7 @@ export const catalogFields: number = Limits.catalogFields
  * @category constants
  * @since 2.0.0
  */
-export const searchSteps: number = Limits.searchSteps
+export const searchSteps: number = Internal.searchSteps
 
 /**
  * The most fields that one search for a value may test. Past it, the answer
@@ -115,7 +154,7 @@ export const searchSteps: number = Limits.searchSteps
  * @category constants
  * @since 2.0.0
  */
-export const searchFields: number = Limits.searchFields
+export const searchFields: number = Internal.searchFields
 
 /**
  * The error when an input goes past a limit.
@@ -124,11 +163,12 @@ export const searchFields: number = Limits.searchFields
  * @category errors
  * @since 2.0.0
  */
-export const LimitExceeded: typeof Limits.LimitExceeded = Limits.LimitExceeded
+export const LimitExceeded: typeof Internal.LimitExceeded =
+	Internal.LimitExceeded
 
 /**
  * @stability stable
  * @category errors
  * @since 2.0.0
  */
-export type LimitExceeded = Limits.LimitExceeded
+export type LimitExceeded = Internal.LimitExceeded

package/src/Policy.ts

@@ -215,6 +215,71 @@ export type KindTarget<D> = {
 	}
 }[Domain.Kind<D>]
 
+/**
+ * A {@link Target} with a field of any length. A function that takes a
+ * target checks its field with {@link CheckField}, so a field of up to about
+ * 1000 parts is fine, and a field that is not a field of the kind is a type
+ * error.
+ *
+ * @stability stable
+ * @category models
+ * @since 2.1.0
+ */
+export type DeepTarget<D> = {
+	[K in Domain.Kind<D>]: {
+		readonly action: Domain.ActionOf<D, K>
+		readonly resource: Domain.ValueOf<D, K>
+		readonly field?: string
+		readonly kind?: never
+	}
+}[Domain.Kind<D>]
+
+/**
+ * A {@link KindTarget} with a field of any length. See {@link DeepTarget}.
+ *
+ * @stability stable
+ * @category models
+ * @since 2.1.0
+ */
+export type DeepKindTarget<D> = {
+	[K in Domain.Kind<D>]: {
+		readonly action: Domain.ActionOf<D, K>
+		readonly kind: K
+		readonly field?: string
+		readonly within?: Scope<D, K>
+		readonly resource?: never
+	}
+}[Domain.Kind<D>]
+
+/** The kind of a target: its `kind`, or the `_tag` of its resource value. */
+type KindOfTarget<T> = T extends { readonly kind: infer K extends string }
+	? K
+	: T extends { readonly resource: { readonly _tag: infer K extends string } }
+		? K
+		: never
+
+/**
+ * Checks the field of a target or a request: a field of its kind that a
+ * request may name, of any length up to about 1000 parts. See
+ * `Condition.SelectPath`. A target with no field needs no check.
+ *
+ * @stability stable
+ * @category utility types
+ * @since 2.1.0
+ */
+export type CheckField<D, T> = T extends { readonly field?: infer F }
+	? [Exclude<F, undefined>] extends [never]
+		? unknown
+		: {
+				// A field that the target may leave out is checked too, when it is
+				// there.
+				readonly field?: Condition.SelectPath<
+					Domain.DataOf<D, KindOfTarget<T>>,
+					Exclude<F, undefined> & string
+				>
+			}
+	: unknown
+
 /**
  * A request: a principal, an action, and a resource value.
  *
@@ -224,6 +289,17 @@ export type KindTarget<D> = {
  */
 export type Request<D> = Target<D> & { readonly principal: Domain.Principal<D> }
 
+/**
+ * A {@link Request} with a field of any length. See {@link DeepTarget}.
+ *
+ * @stability stable
+ * @category models
+ * @since 2.1.0
+ */
+export type DeepRequest<D> = DeepTarget<D> & {
+	readonly principal: Domain.Principal<D>
+}
+
 /**
  * A {@link Request} with no field.
  *
@@ -246,6 +322,17 @@ export type KindRequest<D> = KindTarget<D> & {
 	readonly principal: Domain.Principal<D>
 }
 
+/**
+ * A {@link KindRequest} with a field of any length. See {@link DeepTarget}.
+ *
+ * @stability stable
+ * @category models
+ * @since 2.1.0
+ */
+export type DeepKindRequest<D> = DeepKindTarget<D> & {
+	readonly principal: Domain.Principal<D>
+}
+
 /**
  * A request with no types.
  *
@@ -449,13 +536,34 @@ export type ConditionFor<D, K> = Condition.Condition<
 >
 
 /**
- * The options of a rule.
+ * Checks each field of a rule: a field pattern with a star, or a name of the
+ * kinds `K`, of any length up to about 1000 parts. A name that is not a field
+ * gives the names that may come next, so the type error names them. See
+ * `Condition.NamePath`.
+ *
+ * @stability stable
+ * @category utility types
+ * @since 2.1.0
+ */
+export type FieldsFor<D, K, Fields extends ReadonlyArray<string>> = {
+	readonly [I in keyof Fields]: Fields[I] extends `${string}*${string}`
+		? Fields[I]
+		: Condition.NamePath<DataFor<D, K>, Fields[I] & string>
+}
+
+/**
+ * The options of a rule. `Fields` is the list of the fields of the rule.
  *
  * @stability stable
  * @category models
  * @since 0.3.0
  */
-export interface RuleOptions<D, K, C extends Condition.Any> {
+export interface RuleOptions<
+	D,
+	K,
+	C extends Condition.Any,
+	Fields extends ReadonlyArray<string> = ReadonlyArray<FieldFor<D, K>>,
+> {
 	/** The condition. It gets a builder with the types of the resource. */
 	readonly when?: (
 		builder: Condition.Builder<
@@ -464,7 +572,7 @@ export interface RuleOptions<D, K, C extends Condition.Any> {
 			Domain.Principal<D>
 		>,
 	) => C
-	readonly fields?: ReadonlyArray<FieldFor<D, K>>
+	readonly fields?: Fields & FieldsFor<D, K, Fields>
 	readonly reason?: string
 	readonly id?: string
 	readonly meta?: Domain.Meta<D>
@@ -485,20 +593,22 @@ export interface Builder<D> {
 		const A extends ActionForTargets<D, Res>,
 		const C extends ConditionFor<D, KindOf<TargetOf<Res>>> =
 			Condition.Condition,
+		const Fields extends ReadonlyArray<string> = readonly [],
 	>(
 		action: SingleOrArray<A>,
 		resource: Res,
-		options?: RuleOptions<D, KindOf<TargetOf<Res>>, C>,
+		options?: RuleOptions<D, KindOf<TargetOf<Res>>, C, Fields>,
 	) => Rule<D, Condition.ReadsOf<C>, Condition.OpaqueOf<C>>
 	readonly deny: <
 		const Res extends SingleOrArray<RuleTarget<D>>,
 		const A extends ActionForTargets<D, Res>,
 		const C extends ConditionFor<D, KindOf<TargetOf<Res>>> =
 			Condition.Condition,
+		const Fields extends ReadonlyArray<string> = readonly [],
 	>(
 		action: SingleOrArray<A>,
 		resource: Res,
-		options?: RuleOptions<D, KindOf<TargetOf<Res>>, C>,
+		options?: RuleOptions<D, KindOf<TargetOf<Res>>, C, Fields>,
 	) => Rule<D, Condition.ReadsOf<C>, Condition.OpaqueOf<C>>
 }
 
@@ -688,9 +798,13 @@ export const provideContext: {
  * @category evaluation
  * @since 0.3.0
  */
-export const decide: <D extends Domain.Any, X>(
+export const decide: <
+	D extends Domain.Any,
+	X,
+	const Req extends DeepRequest<NoInfer<D>>,
+>(
 	policy: Policy<D, X>,
-	request: Request<NoInfer<D>>,
+	request: Req & CheckField<NoInfer<D>, Req>,
 ) => Effect.Effect<
 	Decision.Decision,
 	Condition.ErrorOf<X>,
@@ -704,9 +818,12 @@ export const decide: <D extends Domain.Any, X>(
  * @category evaluation
  * @since 0.3.0
  */
-export const decideSync: <D extends Domain.Any>(
+export const decideSync: <
+	D extends Domain.Any,
+	const Req extends DeepRequest<NoInfer<D>>,
+>(
 	policy: Policy<D>,
-	request: Request<NoInfer<D>>,
+	request: Req & CheckField<NoInfer<D>, Req>,
 ) => Decision.Decision = Decide.decideSync
 
 /**
@@ -719,9 +836,13 @@ export const decideSync: <D extends Domain.Any>(
  * @category evaluation
  * @since 0.3.0
  */
-export const explain: <D extends Domain.Any, X>(
+export const explain: <
+	D extends Domain.Any,
+	X,
+	const Req extends DeepRequest<NoInfer<D>>,
+>(
 	policy: Policy<D, X>,
-	request: Request<NoInfer<D>>,
+	request: Req & CheckField<NoInfer<D>, Req>,
 ) => Effect.Effect<Explanation, Condition.ErrorOf<X>, Condition.ServicesOf<X>> =
 	Decide.explain as never
 
@@ -789,8 +910,8 @@ export type ResidualReads<D, K> = Condition.Reads<
  *
  * A policy tree may use the condition of a child two times, so a small policy
  * may give a very large condition. When the condition would have more than
- * 10000 nodes, this function throws an error. In an `Authorizer`, the error
- * is a defect, so the check fails.
+ * the `residualNodes` of the domain, 100000 by default, this function throws
+ * an error. In an `Authorizer`, the error is a defect, so the check fails.
  *
  * @stability stable
  * @category evaluation
@@ -799,10 +920,10 @@ export type ResidualReads<D, K> = Condition.Reads<
 export const residual: <
 	D extends Domain.Any,
 	X,
-	const Req extends KindRequest<NoInfer<D>>,
+	const Req extends DeepKindRequest<NoInfer<D>>,
 >(
 	policy: Policy<D, X>,
-	request: Req,
+	request: Req & CheckField<NoInfer<D>, Req>,
 ) => Condition.Condition<ResidualReads<D, Req["kind"]>, X> =
 	Analysis.residual as never
 
@@ -861,10 +982,10 @@ export type Coverage<I = unknown, X = never> = Data.TaggedEnum<{
 export const coverage: <
 	D extends Domain.Any,
 	X,
-	const Req extends KindRequest<NoInfer<D>>,
+	const Req extends DeepKindRequest<NoInfer<D>>,
 >(
 	policy: Policy<D, X>,
-	request: Req,
+	request: Req & CheckField<NoInfer<D>, Req>,
 ) => Coverage<ResidualReads<D, Req["kind"]>, X> = Analysis.coverageAny as never
 
 // Schema
@@ -915,10 +1036,11 @@ export type EncodedNode =
  * every kind, action, field and principal field against the domain, and the
  * `meta` of each rule against the `meta` Schema of the domain.
  *
- * The decoder takes at most 256 levels of policies and 500 levels of
- * conditions, and at most 1000000 objects and array items, with a shared
- * object counted for each place. It reads only the own data fields of the
- * input.
+ * The decoder takes the limits of the domain: at most `policyNodes` nodes
+ * of the tree, `conditionNodes` nodes of each condition, and `jsonNodes`
+ * objects and array items, with a shared object counted for each place. It
+ * stops at the first one past a limit. It takes any number of levels, and it
+ * reads only the own data fields of the input.
  *
  * @stability stable
  * @category schemas