@nmnmcc/ability 1.0.1 → 2.0.1

package/src/internal/policy.ts

@@ -0,0 +1,264 @@
+/**
+ * The values of policies: the class of a policy, the constructors, the
+ * combinators and the Schema. The types are in `Policy.ts`.
+ */
+import type * as Context from "effect/Context"
+import * as Data from "effect/Data"
+import * as Arr from "effect/Array"
+import * as Effect from "effect/Effect"
+import { dual } from "effect/Function"
+import * as Option from "effect/Option"
+import * as Schema from "effect/Schema"
+import * as SchemaIssue from "effect/SchemaIssue"
+import * as SchemaTransformation from "effect/SchemaTransformation"
+import * as Condition from "../Condition.ts"
+import type * as Domain from "../Domain.ts"
+import type * as Policy from "../Policy.ts"
+import * as Bind from "./bind.ts"
+import * as Nodes from "./nodes.ts"
+import * as PolicyJson from "./policy-json.ts"
+import * as PolicyNodes from "./policy-nodes.ts"
+import * as RuleData from "./rule.ts"
+
+type Any = Policy.Any
+type Node = Policy.Node
+type Options = Policy.Options
+
+/**
+ * The class of every policy value. Two policies of one domain with the same
+ * tree are equal. As JSON, a policy is its tree.
+ */
+export class PolicyData<
+	D extends Domain.Any = any,
+	X = never,
+> extends Data.Class<{
+	readonly domain: D
+	readonly node: Node
+}> {
+	// A private field makes the type of a policy its own: a spread of a
+	// policy, or an object made by hand, is not a policy. `Equal` does not
+	// read it.
+	readonly #policy = true
+	/** Only in the types. */
+	declare readonly "~Opaque": () => X
+	/**
+	 * Only in the types. A policy reads the values and the principal of its
+	 * domain, so a policy of one domain is not a policy of a wider domain.
+	 */
+	declare readonly "~Domain": (domain: D) => D
+
+	toJSON(): unknown {
+		return PolicyJson.toJson(this.node, PolicyJson.syncMeta(this.domain.meta))
+	}
+
+	/** Tests if a value is a policy, by its private field. */
+	static is(u: unknown): u is Any {
+		return typeof u === "object" && u !== null && #policy in u
+	}
+}
+
+/** The node of a policy, with no types, for the code below. */
+export const nodeOf = (policy: Any): PolicyNodes.Node => policy.node as never
+
+export const fromNode = (domain: Domain.Any, node: PolicyNodes.Node): any =>
+	new PolicyData({ domain, node })
+
+/**
+ * The error when a rule does not fit its domain. It has one issue for each
+ * problem, with its path.
+ */
+export class PolicyError extends Schema.TaggedError<PolicyError>(
+	"@nmnmcc/ability/Policy/PolicyError",
+)("PolicyError", {
+	issues: Schema.Array(
+		Schema.Struct({
+			path: Schema.Array(Schema.Union([Schema.String, Schema.Finite])),
+			message: Schema.String,
+		}),
+	),
+	message: Schema.String,
+}) {}
+
+/** Makes a policy from a list of rules, and binds them to the domain. */
+const fromRules = (
+	domain: Domain.Any,
+	values: Iterable<unknown>,
+	options?: Options,
+): Any => {
+	// The constructor takes only rules, and it stops a list past the limits.
+	const node = new PolicyNodes.Rules({
+		algorithm: options?.algorithm ?? "denyOverrides",
+		rules: Array.from(values) as ReadonlyArray<RuleData.Rule>,
+	})
+	// A rule from a builder of another domain is a mistake in the code, so it
+	// is a defect. Two domains may have the same types, so the types do not
+	// find it.
+	if (
+		Arr.some(node.rules, (value) => {
+			const origin = value.domain
+			return origin !== undefined && origin !== domain
+		})
+	) {
+		throw new globalThis.Error(
+			"A rule comes from the builder of another domain",
+		)
+	}
+	// Every rule is bound to the domain here, also a rule from `Policy.rule`.
+	const issues = Bind.treeIssues(domain, node)
+	if (issues.length > 0) {
+		throw PolicyError.make({
+			issues: Arr.map(issues, (issue) => ({
+				path: Arr.map(issue.path, (part) =>
+					typeof part === "number" ? part : String(part),
+				),
+				message: issue.issue,
+			})),
+			message: `A rule does not fit the domain: ${issues.map((issue) => issue.issue).join("; ")}`,
+		})
+	}
+	return fromNode(domain, node)
+}
+
+/** Makes a policy from a generator function that gives rules. */
+export const define =
+	(domain: Domain.Any, options?: Options) =>
+	(body: (builder: unknown) => Generator<unknown, unknown, unknown>): Any => {
+		const iterator = body(RuleData.builder(domain))
+		// Each rule goes back into the generator, as `yield*` gives it.
+		const collected = Arr.unfold(iterator.next(), (state) =>
+			state.done === true
+				? Option.none()
+				: Option.some([state.value, iterator.next(state.value)] as const),
+		)
+		return fromRules(domain, collected, options) as never
+	}
+
+const sameDomain = (policies: ReadonlyArray<Any>): Domain.Any => {
+	// A copy of a policy made with a spread may keep the type fields of another
+	// policy. Only a policy value goes into a tree.
+	if (!Arr.every(policies, isPolicy)) {
+		throw new globalThis.Error("A value in the list is not a policy")
+	}
+	const domain = policies[0]!.domain
+	if (!Arr.every(policies, (policy) => policy.domain === domain)) {
+		throw new globalThis.Error(
+			"Policies from two domains can not be put together",
+		)
+	}
+	return domain
+}
+
+// The constructors of the nodes stop a tree past `policyDepth` or
+// `policyNodes`.
+export const combine =
+	(tag: "All" | "Any" | "FirstOf") =>
+	(policies: ReadonlyArray<Any>): any =>
+		fromNode(
+			sameDomain(policies),
+			new PolicyNodes[tag](Arr.map(policies, nodeOf)),
+		)
+
+/** Puts a limit on a policy. A deny from `cap` always wins. */
+export const ceiling = dual(2, (policy: Any, cap: Any): any =>
+	fromNode(
+		sameDomain([policy, cap]),
+		new PolicyNodes.Ceiling({ cap: nodeOf(cap), policy: nodeOf(policy) }),
+	),
+)
+
+/**
+ * Gives the services to the predicates of a tree. A node with none stays. The
+ * conditions get the services first, from a flat list of the rules, so the
+ * walk does not go down the levels of the tree and of a condition at once.
+ */
+const provideNode = (
+	root: PolicyNodes.Node,
+	context: Context.Context<never>,
+): PolicyNodes.Node => {
+	// A native map, because it must find a rule by the rule itself: two rules
+	// with the same data are `Equal`.
+	const provided = new Map<RuleData.Rule, RuleData.Rule>(
+		Arr.map(PolicyNodes.rulesOf(root), (value) => [
+			value,
+			value.when === undefined || !Nodes.toNode(value.when).opaque
+				? value
+				: RuleData.make({
+						...value,
+						when: Condition.provideContext(
+							value.when as Condition.Any,
+							context as never,
+						),
+					}),
+		]),
+	)
+	const provide = (node: PolicyNodes.Node): PolicyNodes.Node => {
+		if (!node.opaque) {
+			return node
+		}
+		switch (node._tag) {
+			case "Rules":
+				return new PolicyNodes.Rules({
+					algorithm: node.algorithm,
+					rules: Arr.map(node.rules, (value) => provided.get(value) ?? value),
+				})
+			case "All":
+			case "Any":
+			case "FirstOf":
+				return new PolicyNodes[node._tag](Arr.map(node.policies, provide))
+			case "Ceiling":
+				return new PolicyNodes.Ceiling({
+					cap: provide(node.cap),
+					policy: provide(node.policy),
+				})
+		}
+	}
+	return provide(root)
+}
+
+/** Gives the services in `context` to every predicate of a policy. */
+export const provideContext = dual(
+	2,
+	(policy: Any, context: Context.Context<never>): any =>
+		fromNode(policy.domain, provideNode(nodeOf(policy), context)),
+)
+
+/** Tests if a value is a policy. */
+export const isPolicy = (u: unknown): u is Any => PolicyData.is(u)
+
+/** The Schema of the policies of a domain with no predicates. */
+export const schema = (domain: Domain.Any): Schema.Top =>
+	Schema.Unknown.pipe(
+		Schema.decodeTo(
+			// A policy with a predicate is not a plain policy, and it can not
+			// become JSON.
+			Schema.declare(
+				(u): u is Any =>
+					isPolicy(u) && u.domain === domain && !nodeOf(u).opaque,
+			).check(
+				Schema.makeFilter((policy) => Bind.treeIssues(domain, nodeOf(policy))),
+			),
+			SchemaTransformation.transformEffect({
+				decode: (input: unknown, options) =>
+					PolicyJson.decode(input, domain).pipe(
+						Effect.map((node) => fromNode(domain, node)),
+						Effect.mapError(
+							(problem) =>
+								new SchemaIssue.Pointer(
+									problem.path,
+									problem.issue ??
+										new SchemaIssue.InvalidValue(
+											{ message: problem.message },
+											input,
+											options,
+										),
+								),
+						),
+					),
+				encode: (policy: Any) =>
+					Effect.mapError(
+						PolicyJson.encode(nodeOf(policy), domain.meta),
+						(error) => error.issue,
+					),
+			}),
+		),
+	) as never

package/src/internal/read.ts

@@ -0,0 +1,55 @@
+/**
+ * How a condition reads a field of a value. A condition reads only plain
+ * data: an own data field that a loop over the keys sees. This is the data
+ * that a Schema describes, and that every value from Effect has, so the
+ * catalog of the Schema holds every value that a read can give.
+ */
+import * as Arr from "effect/Array"
+import * as Option from "effect/Option"
+
+/** The prototypes of a value, from its own prototype up. */
+const prototypesOf = (value: object): ReadonlyArray<object> =>
+	Arr.unfold(Object.getPrototypeOf(value) as object | null, (prototype) =>
+		prototype === null
+			? Option.none()
+			: Option.some([prototype, Object.getPrototypeOf(prototype)] as const),
+	)
+
+/**
+ * Reads one part of a value:
+ * - an own data field that a loop over the keys sees gives its value, with
+ *   `null` for `undefined`;
+ * - a part of `null`, of a scalar, or a missing field gives `null`;
+ * - a name that the value has only from `Object.prototype`, such as
+ *   `constructor`, gives `null`.
+ *
+ * Any other field, such as a getter, a hidden field, or a field from the
+ * prototype of a class, is a defect. Its value is not data that the Schema
+ * describes, and a read of it as `null` could let a value pass a deny rule.
+ */
+export const readPart = (value: unknown, name: string): unknown => {
+	if (typeof value !== "object" || value === null) {
+		return null
+	}
+	const property = Object.getOwnPropertyDescriptor(value, name)
+	if (property === undefined) {
+		const owner = Arr.findFirst(prototypesOf(value), (prototype) =>
+			Object.hasOwn(prototype, name),
+		)
+		if (Option.isNone(owner) || owner.value === Object.prototype) {
+			return null
+		}
+		throw new Error(`The field "${name}" of the value is not plain data`)
+	}
+	if (!("value" in property) || property.enumerable !== true) {
+		throw new Error(`The field "${name}" of the value is not plain data`)
+	}
+	return property.value === undefined ? null : property.value
+}
+
+/** Reads a field of a value by the names of its parts. */
+export const readPath = (
+	value: unknown,
+	names: ReadonlyArray<string>,
+): unknown =>
+	Arr.reduce(names, value, (current, name) => readPart(current, name))

package/src/internal/resource.ts

@@ -0,0 +1,180 @@
+/**
+ * The values of resources: their descriptors, and the constructors of
+ * `Resource.Class` and `Resource.make`. The types are in `Resource.ts`.
+ */
+import * as Arr from "effect/Array"
+import { Class as DataClass } from "effect/Data"
+import { hasProperty } from "effect/Predicate"
+import * as Schema from "effect/Schema"
+import type {
+	Any,
+	Descriptor,
+	FieldRef,
+	Options,
+	PathSegment,
+} from "../Resource.ts"
+import * as Catalog from "./catalog.ts"
+
+/**
+ * The class of the runtime data of a resource. `isResource` uses it to
+ * know a resource.
+ */
+class ResourceDescriptor extends DataClass<Descriptor> {}
+
+/**
+ * Checks the names of the top fields of a resource at once, when it is made.
+ * The names of nested fields are checked when the descriptor is made.
+ */
+const checkFields = (
+	kind: string,
+	options: Options<ReadonlyArray<string>, Schema.Struct.Fields>,
+): void => {
+	// The kind of a value comes from its `_tag`. A field with this name could
+	// give a value another kind, so it is a defect.
+	if (Object.hasOwn(options.fields, "_tag")) {
+		throw new Error(`The resource "${kind}" may not have a field "_tag"`)
+	}
+	Arr.map(Object.keys(options.fields), (name) => {
+		if (name.includes(".")) {
+			throw new Error(`A field name may not have a dot: "${name}"`)
+		}
+		if (name === "") {
+			throw new Error("A field name may not be empty")
+		}
+	})
+}
+
+/**
+ * Gives a value that is made on first use, and then kept. The descriptor of a
+ * resource reads its Schema, and a recursive Schema refers to the resource
+ * class, so it can not be read while the class is made. The cell belongs to
+ * one resource.
+ */
+const lazy = <A>(make: () => A): (() => A) => {
+	const cell: { value?: A } = {}
+	return () => {
+		if (!("value" in cell)) {
+			cell.value = make()
+		}
+		return cell.value as A
+	}
+}
+
+/**
+ * Checks each part of the path of a resource: a string, or a reference to a
+ * top-level field of the resource. A reference to another field would read
+ * nothing, and a rule on the path could then match a value by mistake.
+ */
+const checkPath = (
+	kind: string,
+	fields: Schema.Struct.Fields,
+	path: ReadonlyArray<unknown>,
+): ReadonlyArray<PathSegment> =>
+	// `Array.from` gives `undefined` for a hole of a sparse array, so the check
+	// sees each place.
+	Arr.map(Array.from(path), (segment): PathSegment => {
+		if (typeof segment === "string") {
+			return segment
+		}
+		if (
+			hasProperty(segment, "_tag") &&
+			segment._tag === "Field" &&
+			hasProperty(segment, "field") &&
+			typeof segment.field === "string" &&
+			Object.hasOwn(fields, segment.field)
+		) {
+			return { _tag: "Field", field: segment.field }
+		}
+		throw new globalThis.Error(
+			`A part of the path of "${kind}" is not a string or a field of the resource`,
+		)
+	})
+
+/**
+ * Copies the options of a resource. The descriptor is made later, when it is
+ * first read, so a change to the objects of the caller before then must not
+ * change it: the Schema of the values and the descriptor must agree.
+ */
+const snapshot = (
+	options: Options<ReadonlyArray<string>, Schema.Struct.Fields>,
+): Options<ReadonlyArray<string>, Schema.Struct.Fields> => ({
+	...options,
+	actions: [...options.actions],
+	fields: { ...options.fields },
+})
+
+const makeDescriptor = (
+	kind: string,
+	options: Options<ReadonlyArray<string>, Schema.Struct.Fields>,
+): Descriptor => {
+	const refs: Record<string, FieldRef<string>> = Object.fromEntries(
+		Arr.map(Object.keys(options.fields), (key) => [
+			key,
+			{ _tag: "Field", field: key },
+		]),
+	)
+	const struct = Schema.Struct(options.fields)
+	return new ResourceDescriptor({
+		kind,
+		actions: [...options.actions],
+		path:
+			options.path === undefined
+				? undefined
+				: checkPath(kind, options.fields, options.path(refs)),
+		catalog: Catalog.catalogOf(struct.ast),
+		schema: Schema.TaggedStruct(kind, options.fields),
+	})
+}
+
+/** Makes the class of `Resource.Class`. */
+export const makeClass =
+	(identifier?: string) =>
+	(
+		kind: string,
+		input: Options<ReadonlyArray<string>, Schema.Struct.Fields>,
+	) => {
+		const options = snapshot(input)
+		checkFields(kind, options)
+		const Base = Schema.TaggedClass<any>(identifier)(kind, options.fields)
+		const descriptor = lazy(() => makeDescriptor(kind, options))
+		return class extends Base {
+			static get descriptor() {
+				return descriptor()
+			}
+			static readonly kind = kind
+			static readonly actions = [...options.actions]
+		}
+	}
+
+/** Makes a resource of `Resource.make`. */
+export const makeStruct = (
+	kind: string,
+	input: Options<ReadonlyArray<string>, Schema.Struct.Fields>,
+) => {
+	const options = snapshot(input)
+	checkFields(kind, options)
+	const schema = Schema.TaggedStruct(kind, options.fields)
+	const descriptor = lazy(() => makeDescriptor(kind, options))
+	return {
+		get descriptor() {
+			return descriptor()
+		},
+		kind,
+		actions: [...options.actions],
+		schema,
+		make: (input: object) => schema.make(input as never),
+	}
+}
+
+/** Tests if a value is a resource. */
+export const isResource = (u: unknown): u is Any =>
+	hasProperty(u, "descriptor") && u.descriptor instanceof ResourceDescriptor
+
+/** Gets the runtime data of a resource. */
+export const descriptor = (resource: Any): Descriptor => resource.descriptor
+
+/** Gives the kind name of a resource value, from its `_tag` field. */
+export const kindOf = (value: unknown): string | undefined =>
+	hasProperty(value, "_tag") && typeof value._tag === "string"
+		? value._tag
+		: undefined

package/src/internal/rule.ts

@@ -0,0 +1,196 @@
+/**
+ * The values of rules, with no types. The types are in `Policy.ts`.
+ *
+ * Rules do not change, and two rules with the same data are equal. A rule
+ * works in a generator: it gives itself, so `yield* _.allow(...)` gives the
+ * rule to `Policy.define`.
+ */
+import * as Arr from "effect/Array"
+import * as Data from "effect/Data"
+import * as Condition from "../Condition.ts"
+import type * as Domain from "../Domain.ts"
+import type * as Resource from "../Resource.ts"
+import * as Catalog from "./catalog.ts"
+import * as Nodes from "./nodes.ts"
+import * as ResourceData from "./resource.ts"
+import * as Patterns from "./patterns.ts"
+
+/** The data of a rule. */
+export interface Shape {
+	readonly _tag: "Allow" | "Deny"
+	readonly actions: ReadonlyArray<string>
+	readonly resources: ReadonlyArray<string>
+	readonly when?: Condition.Ast
+	readonly fields?: ReadonlyArray<string>
+	readonly reason?: string
+	readonly id?: string
+	readonly meta?: unknown
+	/**
+	 * The domain of the builder that made the rule. Two domains may have the
+	 * same types but other paths, so the types can not tell them apart. It is
+	 * not in the JSON form of a rule.
+	 */
+	readonly domain?: Domain.Any
+}
+
+/** The class of every rule value. */
+export class Rule extends Data.Class<Shape> {
+	*[Symbol.iterator](): Generator<this, this, unknown> {
+		yield this
+		return this
+	}
+}
+
+/** Makes a rule from its data. It does not check the data against a domain. */
+export const make = (data: Shape): Rule =>
+	// A missing option is left out, so two rules with the same data are equal.
+	new Rule({
+		_tag: data._tag,
+		actions: [...data.actions],
+		resources: [...data.resources],
+		...(data.when === undefined ? {} : { when: data.when }),
+		...(data.fields === undefined ? {} : { fields: [...data.fields] }),
+		...(data.reason === undefined ? {} : { reason: data.reason }),
+		...(data.id === undefined ? {} : { id: data.id }),
+		...(data.meta === undefined ? {} : { meta: data.meta }),
+		...(data.domain === undefined ? {} : { domain: data.domain }),
+	})
+
+/**
+ * Makes a rule from its data, as `Policy.rule` does. A condition with a
+ * predicate is a defect: the types of the predicate tie it to the kinds of
+ * the rule of a builder, and the binding can not check it.
+ */
+export const makePlain = (data: Shape): Rule => {
+	if (data.when !== undefined && Nodes.isNode(data.when) && data.when.opaque) {
+		throw new Error(
+			"Policy.rule takes no condition with a predicate. Make the rule with Policy.builder.",
+		)
+	}
+	return make(data)
+}
+
+/** Tests if a value is a rule. */
+export const isRule = (u: unknown): u is Rule => u instanceof Rule
+
+const toArray = <A>(value: A | ReadonlyArray<A>): ReadonlyArray<A> =>
+	Array.isArray(value) ? value : [value as A]
+
+const kindName = (target: unknown): string =>
+	ResourceData.isResource(target)
+		? ResourceData.descriptor(target).kind
+		: (target as string)
+
+/** The options of a rule from a builder, with no types. */
+interface Options {
+	readonly when?: (builder: never) => Condition.Ast
+	readonly fields?: ReadonlyArray<string>
+	readonly reason?: string
+	readonly id?: string
+	readonly meta?: unknown
+}
+
+const fromOptions =
+	(tag: "Allow" | "Deny", domain: Domain.Any) =>
+	(
+		action: string | ReadonlyArray<string>,
+		resource: unknown,
+		options?: Options,
+	): Rule =>
+		make({
+			_tag: tag,
+			actions: toArray(action),
+			resources: Arr.map(toArray(resource), kindName),
+			...(options?.when === undefined
+				? {}
+				: { when: options.when(Condition.builder() as never) }),
+			...(options?.fields === undefined ? {} : { fields: options.fields }),
+			...(options?.reason === undefined ? {} : { reason: options.reason }),
+			...(options?.id === undefined ? {} : { id: options.id }),
+			...(options?.meta === undefined ? {} : { meta: options.meta }),
+			domain,
+		})
+
+/** Makes the rule builder of a domain. */
+export const builder = (domain: Domain.Any) => ({
+	allow: fromOptions("Allow", domain),
+	deny: fromOptions("Deny", domain),
+})
+
+/**
+ * Tests if a field name matches a field name or a field pattern of a rule. A
+ * pattern matches the fields below a field that it matches too, so `settings`
+ * matches `settings.model`.
+ */
+export const matchesField = (pattern: string, field: string): boolean =>
+	Patterns.matches(Patterns.parseBound(pattern), field.split("."))
+
+/**
+ * Tests if a field pattern may match a field inside `field`, such as
+ * `settings.secret` inside `settings`.
+ */
+export const matchesInside = (pattern: string, field: string): boolean =>
+	Patterns.matchesBelow(Patterns.parseBound(pattern), field.split("."))
+
+/**
+ * Tests the parts of a rule that do not need the resource value: the action,
+ * the kind and the field.
+ *
+ * A rule with an empty list of fields covers no request. A rule with fields
+ * covers a request with no field only when it is an allow rule. So "may
+ * update some fields" is a yes. A deny rule for some fields does not stop a
+ * request for the whole value. With the `descriptor` of the kind, such an
+ * allow rule covers the request only when one of its patterns matches a field
+ * of the kind, and a deny rule for a part of a field that holds parts covers
+ * a request for the whole field. A grant of fields that the kind does not have is not a grant of
+ * some fields.
+ */
+export const matchesTarget = (
+	rule: Shape,
+	target: {
+		readonly action: string
+		readonly kind: string
+		readonly field?: string | undefined
+		readonly descriptor?: Resource.Descriptor | undefined
+	},
+): boolean => {
+	if (!rule.actions.includes("*") && !rule.actions.includes(target.action)) {
+		return false
+	}
+	if (!rule.resources.includes("*") && !rule.resources.includes(target.kind)) {
+		return false
+	}
+	if (rule.fields === undefined) {
+		return true
+	}
+	// A rule for no fields is a rule for nothing. A grant with its last field
+	// taken away must not cover the whole value.
+	if (rule.fields.length === 0) {
+		return false
+	}
+	if (target.field === undefined) {
+		const descriptor = target.descriptor
+		return (
+			rule._tag === "Allow" &&
+			(descriptor === undefined ||
+				Arr.some(rule.fields, (pattern) =>
+					Patterns.fitsCatalog(
+						Patterns.parseBound(pattern),
+						descriptor.catalog,
+					),
+				))
+		)
+	}
+	const field = target.field
+	// A field that holds parts, as a record does, shows its parts too. So a
+	// deny rule for a part inside it, as `data.secret` inside `data`, also
+	// covers a request for the whole field.
+	const open =
+		rule._tag === "Deny" &&
+		target.descriptor !== undefined &&
+		(Catalog.lookup(target.descriptor.catalog, field)?.open ?? false)
+	return rule.fields.some(
+		(pattern) =>
+			matchesField(pattern, field) || (open && matchesInside(pattern, field)),
+	)
+}