@nmnmcc/ability 0.2.0 → 0.3.0

package/src/Decision.ts

@@ -0,0 +1,117 @@
+/**
+ * A decision is the answer of a policy to a request:
+ * - `Allow`: a rule lets the principal do the act.
+ * - `Deny`: a rule stops the principal.
+ * - `NotApplicable`: no rule gives an answer.
+ *
+ * `NotApplicable` is not the same as `Deny`. A check treats it as a "no", but
+ * an `Authorizer` with a decider asks the decider first. See
+ * `Authorizer.Options.decider`.
+ *
+ * @stability stable
+ * @since 0.3.0
+ */
+import * as Data from "effect/Data"
+import type * as Rule from "./Rule.ts"
+
+/**
+ * @stability stable
+ * @category models
+ * @since 0.3.0
+ */
+export type Decision = Data.TaggedEnum<{
+	Allow: {
+		/** The rule that gave the answer, when a rule gave it. */
+		readonly rule?: Rule.Any
+	}
+	Deny: {
+		/** The rule that gave the answer, when a rule gave it. */
+		readonly rule?: Rule.Any
+		readonly reason?: string
+	}
+	NotApplicable: {}
+}>
+
+const {
+	$is,
+	$match,
+	Allow: allow,
+	Deny: deny,
+	NotApplicable: notApplicable,
+} = Data.taggedEnum<Decision>()
+
+/**
+ * @stability stable
+ * @category constructors
+ * @since 0.3.0
+ */
+export const Allow: (args: { readonly rule?: Rule.Any }) => Decision = allow
+
+/**
+ * @stability stable
+ * @category constructors
+ * @since 0.3.0
+ */
+export const Deny: (args: {
+	readonly rule?: Rule.Any
+	readonly reason?: string
+}) => Decision = deny
+
+/**
+ * @stability stable
+ * @category constructors
+ * @since 0.3.0
+ */
+export const NotApplicable: Decision = notApplicable()
+
+/**
+ * @stability stable
+ * @category guards
+ * @since 0.3.0
+ */
+export const isAllow: (
+	decision: Decision,
+) => decision is Extract<Decision, { readonly _tag: "Allow" }> = $is("Allow")
+
+/**
+ * @stability stable
+ * @category guards
+ * @since 0.3.0
+ */
+export const isDeny: (
+	decision: Decision,
+) => decision is Extract<Decision, { readonly _tag: "Deny" }> = $is("Deny")
+
+/**
+ * @stability stable
+ * @category guards
+ * @since 0.3.0
+ */
+export const isNotApplicable: (
+	decision: Decision,
+) => decision is Extract<Decision, { readonly _tag: "NotApplicable" }> =
+	$is("NotApplicable")
+
+/**
+ * Matches each kind of decision.
+ *
+ * @stability stable
+ * @category pattern matching
+ * @since 0.3.0
+ */
+export const match = $match
+
+/**
+ * The reason of a decision: the reason of a `Deny`, or the reason of the rule
+ * that gave the answer.
+ *
+ * @stability stable
+ * @category getters
+ * @since 0.3.0
+ */
+export const reason = (decision: Decision): string | undefined =>
+	decision._tag === "Deny"
+		? (decision.reason ?? decision.rule?.reason)
+		: decision._tag === "Allow"
+			? decision.rule?.reason
+			: undefined

package/src/Domain.ts

@@ -0,0 +1,189 @@
+/**
+ * A domain puts together the principal and all the resources of an
+ * application. All other modules get their types from the domain. A rule may
+ * only use the actions of its resource. A condition may only use the fields of
+ * its resource and of the principal.
+ *
+ * @example
+ * ```ts
+ * import { Domain } from "@nmnmcc/ability"
+ *
+ * const App = Domain.make({ principal: Caller, resources: [Bot, Trigger] })
+ * ```
+ *
+ * @stability stable
+ * @since 0.3.0
+ */
+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
+
+/**
+ * A domain. `P` is the type of the principal, `Resources` is the union of the
+ * resources, and `Meta` is the type of the extra data that a rule may keep.
+ *
+ * @stability stable
+ * @category models
+ * @since 0.3.0
+ */
+export interface Domain<
+	P extends object,
+	Resources extends Resource.Any,
+	Meta,
+> {
+	readonly [TypeId]: TypeId
+	readonly principal: PrincipalSchema.Any
+	readonly resources: ReadonlyMap<string, Resource.Descriptor>
+	readonly meta: Schema.Top | undefined
+	readonly "~Domain"?: {
+		readonly Principal: P
+		readonly Resources: Resources
+		readonly Meta: Meta
+	}
+}
+
+/**
+ * Any domain.
+ *
+ * @stability stable
+ * @category models
+ * @since 0.3.0
+ */
+export type Any = Domain<any, any, any>
+
+/**
+ * The type of the principal of a domain.
+ *
+ * @stability stable
+ * @category utility types
+ * @since 0.3.0
+ */
+export type Principal<D> = D extends Domain<infer P, any, any> ? P : never
+
+/**
+ * The union of the resources of a domain.
+ *
+ * @stability stable
+ * @category utility types
+ * @since 0.3.0
+ */
+export type Resources<D> = D extends Domain<any, infer R, any> ? R : never
+
+/**
+ * The type of the extra data that a rule of the domain may keep.
+ *
+ * @stability stable
+ * @category utility types
+ * @since 0.3.0
+ */
+export type Meta<D> = D extends Domain<any, any, infer M> ? M : never
+
+/**
+ * The kind names of a domain.
+ *
+ * @stability stable
+ * @category utility types
+ * @since 0.3.0
+ */
+export type Kind<D> = Resource.Kind<Resources<D>>
+
+/**
+ * The resource of a domain with the kind `K`.
+ *
+ * @stability stable
+ * @category utility types
+ * @since 0.3.0
+ */
+export type ResourceOf<D, K extends string> =
+	Resources<D> extends infer R
+		? R extends Resource.Resource<K, any, any, any>
+			? R
+			: never
+		: never
+
+/**
+ * The actions of the resource with the kind `K`.
+ *
+ * @stability stable
+ * @category utility types
+ * @since 0.3.0
+ */
+export type ActionOf<D, K extends string> = Resource.Action<ResourceOf<D, K>>
+
+/**
+ * All the actions of all the resources of a domain.
+ *
+ * @stability stable
+ * @category utility types
+ * @since 0.3.0
+ */
+export type AnyAction<D> = Resource.Action<Resources<D>>
+
+/**
+ * The data type of the resource with the kind `K`.
+ *
+ * @stability stable
+ * @category utility types
+ * @since 0.3.0
+ */
+export type DataOf<D, K extends string> = Resource.Data<ResourceOf<D, K>>
+
+/**
+ * The value type of the resource with the kind `K`.
+ *
+ * @stability stable
+ * @category utility types
+ * @since 0.3.0
+ */
+export type ValueOf<D, K extends string> = Resource.Value<ResourceOf<D, K>>
+
+/**
+ * The union of the value types of all the resources of a domain.
+ *
+ * @stability stable
+ * @category utility types
+ * @since 0.3.0
+ */
+export type AnyValue<D> = Resource.Value<Resources<D>>
+
+/**
+ * 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.
+ *
+ * @stability stable
+ * @category constructors
+ * @since 0.3.0
+ */
+export const make: <
+	P extends PrincipalSchema.Any,
+	const Resources extends ReadonlyArray<Resource.Any>,
+	M extends Schema.Top = Schema.Never,
+>(options: {
+	readonly principal: P
+	readonly resources: Resources
+	readonly meta?: M
+}) => Domain<P["Type"], Resources[number], M["Type"]> = internal.make
+
+/**
+ * Tests if a value is a domain.
+ *
+ * @stability stable
+ * @category guards
+ * @since 0.3.0
+ */
+export const isDomain: (u: unknown) => u is Any = internal.isDomain

package/src/HttpApi.ts

@@ -0,0 +1,148 @@
+/**
+ * Tools to check authorization in an `effect/http-api` server.
+ *
+ * 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.
+ *
+ * ```ts
+ * class Authorization extends HttpApiMiddleware.Service<
+ *   Authorization,
+ *   { requires: Identity }
+ * >()("app/Authorization", { error: HttpApi.errors }) {}
+ *
+ * const endpoint = HttpApiEndpoint.patch("update", "/bots/:id", { ... })
+ *   .annotate(HttpApi.Required, [
+ *     HttpApi.requires(Auth, "update", "Bot", (params) => Bots.find(params.id)),
+ *   ])
+ *
+ * const AuthorizationLive = HttpApi.layer(Authorization, Auth)
+ * ```
+ *
+ * This module is a separate entry point, `@nmnmcc/ability/HttpApi`, because
+ * `effect/http-api` is not stable yet.
+ *
+ * @stability unstable
+ * @since 0.3.0
+ */
+import * as Context from "effect/Context"
+import type * as Effect from "effect/Effect"
+import type * as Layer from "effect/Layer"
+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"
+
+/**
+ * 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.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export interface Requirement {
+	readonly action: string
+	readonly kind: string
+	readonly load?: (
+		params: Readonly<Record<string, string | undefined>>,
+	) => Effect.Effect<object, unknown, unknown>
+}
+
+/**
+ * The checks that an endpoint needs.
+ *
+ * @stability unstable
+ * @category annotations
+ * @since 0.3.0
+ */
+export class Required extends Context.Service<
+	Required,
+	ReadonlyArray<Requirement>
+>()("@nmnmcc/ability/HttpApi/Required") {}
+
+/**
+ * The checks for every endpoint of a group with no {@link Required}
+ * annotation. `read` is for GET requests. `write` is for all other methods.
+ *
+ * @stability unstable
+ * @category annotations
+ * @since 0.3.0
+ */
+export class GroupRequired extends Context.Service<
+	GroupRequired,
+	{
+		readonly read: ReadonlyArray<Requirement>
+		readonly write: ReadonlyArray<Requirement>
+	}
+>()("@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.
+ *
+ * `load` may fail. Its errors must be errors of the middleware, and the
+ * services that it needs must be given to {@link layer}.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.3.0
+ */
+export const requires: <
+	A extends { readonly domain: Domain.Any },
+	const K extends Domain.Kind<A["domain"]>,
+>(
+	authorizer: A,
+	action: Domain.ActionOf<A["domain"], K>,
+	kind: K,
+	load?: (
+		params: Readonly<Record<string, string | undefined>>,
+	) => Effect.Effect<Domain.ValueOf<A["domain"], K>, unknown, unknown>,
+) => Requirement = internal.requires
+
+/**
+ * The errors of the middleware, with HTTP status codes: 403 for
+ * `Forbidden`, 503 for `PolicyUnavailable`, and 409 for `Pending`.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 0.3.0
+ */
+export const errors = [
+	Authorizer.Forbidden.pipe(HttpApiSchema.status(403)),
+	Authorizer.PolicyUnavailable.pipe(HttpApiSchema.status(503)),
+	Authorizer.Pending.pipe(HttpApiSchema.status(409)),
+] as const
+
+/**
+ * Makes the layer of an authorization middleware. The middleware reads the
+ * {@link Required} and {@link GroupRequired} annotations and checks each
+ * requirement with the authorizer.
+ *
+ * The layer takes the authorizer when it is built. The middleware must
+ * require the services of the authorizer, such as the identity of the
+ * caller. `R` is the type of the services that the `load` functions need. The
+ * layer takes them when it is built too.
+ *
+ * @stability unstable
+ * @category layers
+ * @since 0.3.0
+ */
+export const layer: <
+	Self,
+	Id extends string,
+	A extends Authorizer.AnyServiceClass,
+	R = never,
+>(
+	middleware: Context.ServiceClass<Self, Id, any>,
+	authorizer: A,
+) => Layer.Layer<
+	Self,
+	never,
+	(A extends Context.Key<infer I, any> ? I : never) | R
+> = internal.layer as never