@kutur-kit/access 0.0.0-stage → 0.1.0-alpha.1

package/src/Condition.ts

@@ -0,0 +1,93 @@
+import { Data, Match, Predicate } from "effect";
+
+/** The values conditions compare. */
+export type Value = string | number | boolean | bigint | null;
+
+/** The fields of `T` a condition can compare: those holding primitive values. */
+export type Field<T> = {
+  readonly [K in keyof T & string]: T[K] extends Value ? K : never;
+}[keyof T & string];
+
+export class All extends Data.TaggedClass("All")<{}> {}
+
+export class None extends Data.TaggedClass("None")<{}> {}
+
+export class Eq extends Data.TaggedClass("Eq")<{
+  readonly field: string;
+  readonly value: Value;
+}> {}
+
+export class OneOf extends Data.TaggedClass("OneOf")<{
+  readonly field: string;
+  readonly values: ReadonlyArray<Value>;
+}> {}
+
+export class And extends Data.TaggedClass("And")<{ readonly conditions: ReadonlyArray<Node> }> {}
+
+export class Or extends Data.TaggedClass("Or")<{ readonly conditions: ReadonlyArray<Node> }> {}
+
+export class Not extends Data.TaggedClass("Not")<{ readonly condition: Node }> {}
+
+export type Node = All | None | Eq | OneOf | And | Or | Not;
+
+/**
+ * A condition over targets of type `T`. The phantom member keeps conditions
+ * over one target type from being used for another.
+ */
+export type Condition<T> = Node & { readonly "~target"?: (target: T) => T };
+
+/** Builds conditions over one target type; PermissionFilter policies receive it. */
+export interface Builder<T> {
+  readonly all: () => Condition<T>;
+  readonly none: () => Condition<T>;
+  readonly eq: <K extends Field<T>>(field: K, value: T[K] & Value) => Condition<T>;
+  readonly oneOf: <K extends Field<T>>(
+    field: K,
+    values: ReadonlyArray<T[K] & Value>,
+  ) => Condition<T>;
+  readonly and: (...conditions: ReadonlyArray<Condition<T>>) => Condition<T>;
+  readonly or: (...conditions: ReadonlyArray<Condition<T>>) => Condition<T>;
+  readonly not: (condition: Condition<T>) => Condition<T>;
+}
+
+export const make = <T>(): Builder<T> => ({
+  all: () => new All(),
+  none: () => new None(),
+  eq: (field, value) => new Eq({ field, value }),
+  oneOf: (field, values) => new OneOf({ field, values }),
+  and: (...conditions) => new And({ conditions }),
+  or: (...conditions) => new Or({ conditions }),
+  not: (condition) => new Not({ condition }),
+});
+
+// NaN equals NaN and 0 equals -0, as in SQL.
+const same = (actual: Value | undefined, value: Value) =>
+  actual === value || Object.is(actual, value);
+
+const isValue = (value: unknown): value is Value =>
+  value === null ||
+  Predicate.isString(value) ||
+  Predicate.isNumber(value) ||
+  Predicate.isBoolean(value) ||
+  Predicate.isBigInt(value);
+
+const evaluate = (fields: ReadonlyMap<string, Value>): ((node: Node) => boolean) =>
+  Match.type<Node>().pipe(
+    Match.tagsExhaustive({
+      All: () => true,
+      None: () => false,
+      Eq: ({ field, value }) => same(fields.get(field), value),
+      OneOf: ({ field, values }) => values.some((value) => same(fields.get(field), value)),
+      And: ({ conditions }) => conditions.every(evaluate(fields)),
+      Or: ({ conditions }) => conditions.some(evaluate(fields)),
+      Not: ({ condition }) => !evaluate(fields)(condition),
+    }),
+  );
+
+/** Whether a target satisfies a condition, as a query applying it would decide. */
+export const matches = <T extends object>(condition: Condition<T>, target: T): boolean =>
+  evaluate(
+    new Map(
+      Object.entries(target).flatMap(([field, value]) => (isValue(value) ? [[field, value]] : [])),
+    ),
+  )(condition);

package/src/Decision.ts

@@ -0,0 +1,45 @@
+import { Data, Schema } from "effect";
+
+export type Decision = Data.TaggedEnum<{
+  Allow: {};
+  /**
+   * `restriction` when the caller's restriction refused the permission before
+   * its policy ran; `requirement` when the policy required a permission, named
+   * by `requirement`, that refused.
+   */
+  Deny: {
+    readonly by: "restriction" | "policy" | "requirement";
+    readonly reason?: string;
+    readonly requirement?: string;
+  };
+}>;
+
+export type Allow = Extract<Decision, { readonly _tag: "Allow" }>;
+
+export type Deny = Extract<Decision, { readonly _tag: "Deny" }>;
+
+const constructors = Data.taggedEnum<Decision>();
+
+export const allow = (): Allow => constructors.Allow();
+
+export const deny = (reason?: string): Deny =>
+  constructors.Deny(reason === undefined ? { by: "policy" } : { by: "policy", reason });
+
+export const restricted = (): Deny => constructors.Deny({ by: "restriction" });
+
+export const unmet = (requirement: string): Deny =>
+  constructors.Deny({ by: "requirement", requirement });
+
+export class Denied extends Schema.TaggedError<Denied, { readonly brand: unique symbol }>()(
+  "AccessDenied",
+  { permission: Schema.String },
+  { httpApiStatus: 403 },
+) {}
+
+export type DeniedBy<P extends string> = Denied & { readonly permission: P };
+
+export type DeniedBySchema<P extends string> = Schema.refine<DeniedBy<P>, typeof Denied>;
+
+/** The refusals of one permission, from its id alone. */
+export const deniedBy = <P extends string>(permission: P): DeniedBySchema<P> =>
+  Denied.pipe(Schema.refine((denied): denied is DeniedBy<P> => denied.permission === permission));

package/src/Permission.ts

@@ -0,0 +1,311 @@
+import type { Scope } from "effect";
+
+import { Context, Effect, Layer, Predicate, Schema, SchemaTransformation } from "effect";
+
+import * as Decision from "./Decision.ts";
+
+export type Codec = Schema.Codec<unknown, unknown>;
+
+export interface Config {
+  readonly requires?: unknown;
+}
+
+export interface Definition {
+  readonly id?: string;
+  readonly target?: Codec;
+  readonly error?: Codec;
+}
+
+export type IdOf<Key extends string, D extends Definition> = D extends {
+  readonly id: infer I extends string;
+}
+  ? I
+  : Key;
+
+export type Requires<C extends Config> = C extends { readonly requires: infer R } ? R : never;
+
+export type TargetOf<D extends Definition> = D extends { readonly target: infer S extends Codec }
+  ? S["Type"]
+  : never;
+
+export type TargetArgs<D extends Definition> = D extends { readonly target: Codec }
+  ? [target: TargetOf<D>]
+  : [];
+
+export type PolicyError<D extends Definition> = D extends {
+  readonly error: infer S extends Codec;
+}
+  ? S["Type"]
+  : never;
+
+/** The errors a check can fail with: refusals of required permissions become decisions. */
+export type CheckError<D extends Definition> = Exclude<PolicyError<D>, Refusal<D>>;
+
+type Refusal<D extends Definition> = Extract<PolicyError<D>, Decision.Denied>;
+
+export type Policy<D extends Definition, R> = (
+  ...target: TargetArgs<D>
+) => Decision.Decision | Effect.Effect<Decision.Decision, PolicyError<D>, R>;
+
+export interface Api<I extends string, D extends Definition, R> {
+  readonly check: (...target: TargetArgs<D>) => Effect.Effect<Decision.Decision, CheckError<D>, R>;
+  readonly require: (
+    ...target: TargetArgs<D>
+  ) => Effect.Effect<void, Decision.DeniedBy<I> | PolicyError<D>, R>;
+}
+
+export interface Statics<Self, I extends string, D extends Definition, R> {
+  readonly id: I;
+  readonly definition: D;
+  readonly Denied: Decision.DeniedBySchema<I>;
+  readonly check: (
+    ...target: TargetArgs<D>
+  ) => Effect.Effect<Decision.Decision, CheckError<D>, Self | R>;
+  readonly require: (
+    ...target: TargetArgs<D>
+  ) => Effect.Effect<void, Decision.DeniedBy<I> | PolicyError<D>, Self | R>;
+  readonly toLayer: <E = never, RL = never>(
+    policy: Policy<D, R> | Effect.Effect<Policy<D, R>, E, RL>,
+  ) => Layer.Layer<Self, E, Exclude<RL, Scope.Scope>>;
+}
+
+export type Permission<Self, Key extends string, D extends Definition, R> = Context.ServiceClass<
+  Self,
+  Key,
+  Api<IdOf<Key, D>, D, R>
+> &
+  Statics<Self, IdOf<Key, D>, D, R>;
+
+export interface Any {
+  readonly id: string;
+  /** The service key: unique per permission, as Effect requires of service keys. */
+  readonly key: string;
+}
+
+export interface Tag<Self, I extends string, D extends Definition, R> extends Context.Service<
+  Self,
+  Api<I, D, R>
+> {
+  readonly id: I;
+  readonly definition: D;
+}
+
+/**
+ * The keys of the permissions the caller may use, or undefined for all.
+ * Keys rather than ids, so permissions sharing an id stay apart.
+ */
+export class Restriction extends Context.Reference<ReadonlySet<string> | undefined>(
+  "@kutur-kit/access/Permission/Restriction",
+  { defaultValue: () => undefined },
+) {}
+
+export interface Decided<D extends Definition> {
+  readonly permission: string;
+  readonly via: "check" | "require";
+  readonly target: TargetArgs<D>;
+  readonly decision: Decision.Decision;
+}
+
+interface Internals<I extends string, D extends Definition, R> {
+  readonly key: string;
+  readonly id: I;
+  readonly decide: (
+    via: Decided<D>["via"],
+    target: ReadonlyArray<unknown>,
+  ) => Effect.Effect<Decided<D>, CheckError<D>, R>;
+}
+
+// True while a check runs, so requires inside its policies only answer it too.
+const Answering = Context.Reference<boolean>("@kutur-kit/access/Permission/Answering", {
+  defaultValue: () => false,
+});
+
+// A WeakMap rather than a field keeps services from Layer.succeed valid.
+const internals = new WeakMap<object, unknown>();
+
+const make = <I extends string, D extends Definition, R>(
+  internal: Internals<I, D, R>,
+): Api<I, D, R> => {
+  const { key, id, decide } = internal;
+
+  const run = Effect.fnUntraced(function* (via: Decided<D>["via"], target: ReadonlyArray<unknown>) {
+    const answering = (yield* Answering) || via === "check";
+
+    const { decision } = yield* decide(answering ? "check" : via, target).pipe(
+      Effect.provideService(Answering, answering),
+    );
+
+    yield* Effect.annotateCurrentSpan({
+      "access.permission": id,
+      "access.decision": decision._tag,
+      ...(Predicate.isTagged(decision, "Deny") && {
+        "access.denied_by": decision.by,
+        ...(decision.reason !== undefined && { "access.reason": decision.reason }),
+        ...(decision.requirement !== undefined && { "access.requirement": decision.requirement }),
+      }),
+    });
+
+    return decision;
+  });
+
+  const check = Effect.fn(`${key}.check`)(function* (...target: ReadonlyArray<unknown>) {
+    return yield* run("check", target);
+  });
+
+  const require = Effect.fn(`${key}.require`)(function* (...target: ReadonlyArray<unknown>) {
+    const decision = yield* run("require", target);
+
+    // A required permission's refusal fails as that permission's, as it would
+    // without this one, so callers can still tell which refused.
+    return yield* Predicate.isTagged(decision, "Deny")
+      ? Effect.fail(new Decision.Denied({ permission: decision.requirement ?? id }))
+      : Effect.void;
+  });
+
+  // SAFETY: Callers pass the arguments TargetArgs<D> describes, and Denied
+  // carries this permission's id.
+  const service = { check, require } as Api<I, D, R>;
+
+  internals.set(service, internal);
+
+  return service;
+};
+
+/**
+ * Runs `f` after every decision of a permission service built by `toLayer`,
+ * inside the check's span and before `require` fails.
+ */
+export const tap =
+  <D extends Definition>(f: (decided: Decided<D>) => Effect.Effect<void>) =>
+  <I extends string, R>(service: Api<I, D, R>): Api<I, D, R> => {
+    // SAFETY: make stored the Internals of this service's I, D and R.
+    const internal = internals.get(service) as Internals<I, D, R> | undefined;
+
+    if (internal === undefined)
+      throw new Error("Permission.tap needs a permission service built by toLayer");
+
+    return make({
+      ...internal,
+      decide: (via, target) => Effect.tap(internal.decide(via, target), f),
+    });
+  };
+
+/** Whether the caller's restriction excludes a permission, so it must refuse. */
+export const isRestricted = (permission: Any) =>
+  Effect.map(Restriction, (allowed) => allowed !== undefined && !allowed.has(permission.key));
+
+export const restrictTo =
+  (permissions: Iterable<Any>) =>
+  <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+    Effect.flatMap(Restriction, (current) => {
+      const allowed = Array.from(permissions, ({ key }) => key);
+
+      return Effect.provideService(
+        effect,
+        Restriction,
+        new Set(current === undefined ? allowed : allowed.filter((key) => current.has(key))),
+      );
+    });
+
+export interface PermissionSet<P extends Any> {
+  readonly schema: Schema.Codec<ReadonlyArray<P["id"]>, ReadonlyArray<string>>;
+  readonly restrictTo: (
+    ids: Iterable<P["id"]>,
+  ) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+}
+
+export const set = <const Ps extends readonly [Any, ...ReadonlyArray<Any>]>(
+  permissions: Ps,
+): PermissionSet<Ps[number]> => {
+  type P = Ps[number];
+
+  const ids = permissions.map((permission): P["id"] => permission.id);
+  const duplicate = ids.find((id, index) => ids.indexOf(id) !== index);
+
+  if (duplicate !== undefined)
+    throw new Error(`Permission id ${duplicate} is used by more than one permission`);
+
+  // Ids name permissions outside the code, such as in stored token scopes.
+  const byId = new Map(permissions.map((permission) => [permission.id, permission]));
+  const isKnown = (id: string): id is P["id"] => byId.has(id);
+
+  const schema = Schema.Array(Schema.String).pipe(
+    Schema.decodeTo(
+      Schema.Array(Schema.Literals(ids)),
+      SchemaTransformation.transform<ReadonlyArray<P["id"]>, ReadonlyArray<string>>({
+        decode: (stored) => stored.filter(isKnown),
+        encode: (decoded) => decoded,
+      }),
+    ),
+  );
+
+  return {
+    schema,
+    restrictTo: (allowed) => restrictTo(Array.from(allowed).flatMap((id) => byId.get(id) ?? [])),
+  };
+};
+
+export const Service =
+  <Self, C extends Config = {}>() =>
+  <const Key extends string, const D extends Definition>(
+    key: Key,
+    definition: D,
+  ): Permission<Self, Key, D, Requires<C>> => {
+    type R = Requires<C>;
+
+    // SAFETY: IdOf<Key, D> is the declared id, or the key without one.
+    const id = (definition.id ?? key) as IdOf<Key, D>;
+
+    const Tag = Context.Service<Self, Api<IdOf<Key, D>, D, R>>()(key);
+
+    const restricted = isRestricted({ id, key });
+
+    const toLayer: Statics<Self, IdOf<Key, D>, D, R>["toLayer"] = (policy) =>
+      Layer.effect(
+        Tag,
+        Effect.gen(function* () {
+          // SAFETY: Callers pass the arguments TargetArgs<D> describes.
+          const resolved = (Effect.isEffect(policy) ? yield* policy : policy) as (
+            ...target: ReadonlyArray<unknown>
+          ) => Decision.Decision | Effect.Effect<Decision.Decision, PolicyError<D>, R>;
+
+          const decide: Internals<IdOf<Key, D>, D, R>["decide"] = Effect.fnUntraced(
+            function* (via, target) {
+              const result = (yield* restricted) ? Decision.restricted() : resolved(...target);
+
+              const refusal = (error: PolicyError<D>): error is Refusal<D> =>
+                Schema.is(Decision.Denied)(error);
+
+              const answered = (answer: Effect.Effect<Decision.Decision, PolicyError<D>, R>) =>
+                answer.pipe(
+                  Effect.catchIf(refusal, (denied) =>
+                    Effect.succeed(Decision.unmet(denied.permission)),
+                  ),
+                );
+
+              const decision = Effect.isEffect(result) ? yield* answered(result) : result;
+
+              // SAFETY: Callers pass the arguments TargetArgs<D> describes.
+              return { permission: id, via, target: target as TargetArgs<D>, decision };
+            },
+          );
+
+          return Tag.of(make({ key, id, decide }));
+        }),
+      );
+
+    const check: Statics<Self, IdOf<Key, D>, D, R>["check"] = (...target) =>
+      Tag.use((permission) => permission.check(...target));
+
+    const require: Statics<Self, IdOf<Key, D>, D, R>["require"] = (...target) =>
+      Tag.use((permission) => permission.require(...target));
+
+    return Object.assign(Tag, {
+      id,
+      definition,
+      Denied: Decision.deniedBy(id),
+      toLayer,
+      check,
+      require,
+    });
+  };

package/src/PermissionFilter.ts

@@ -0,0 +1,93 @@
+import type { Scope } from "effect";
+
+import { Context, Effect, Layer } from "effect";
+
+import * as Condition from "./Condition.ts";
+import * as Permission from "./Permission.ts";
+
+export type Policy<D extends Permission.Definition, R> = (
+  where: Condition.Builder<Permission.TargetOf<D>>,
+) =>
+  | Condition.Condition<Permission.TargetOf<D>>
+  | Effect.Effect<Condition.Condition<Permission.TargetOf<D>>, Permission.CheckError<D>, R>;
+
+export interface Api<D extends Permission.Definition, R> {
+  /** The targets the permission allows, or none outside the caller's restriction. */
+  readonly condition: Effect.Effect<
+    Condition.Condition<Permission.TargetOf<D>>,
+    Permission.CheckError<D>,
+    R
+  >;
+}
+
+export interface Statics<Self, D extends Permission.Definition, R> {
+  readonly condition: Effect.Effect<
+    Condition.Condition<Permission.TargetOf<D>>,
+    Permission.CheckError<D>,
+    Self | R
+  >;
+  readonly toLayer: <E = never, RL = never>(
+    policy: Policy<D, R> | Effect.Effect<Policy<D, R>, E, RL>,
+  ) => Layer.Layer<Self, E, Exclude<RL, Scope.Scope>>;
+}
+
+export type PermissionFilter<Self, D extends Permission.Definition, R> = Context.ServiceClass<
+  Self,
+  string,
+  Api<D, R>
+> &
+  Statics<Self, D, R>;
+
+/**
+ * Defines the query form of a permission: the condition its policy allows,
+ * for listing targets in one query. Its key is the permission's with
+ * `/Filter`, so name the class after the permission too, such as
+ * `ViewInvoiceFilter`. Its policy must agree with the permission's;
+ * `PermissionTesting.assertFilterAgrees` checks that.
+ */
+export const Service =
+  <Self>() =>
+  <
+    PermissionSelf,
+    I extends string,
+    D extends Permission.Definition & { readonly target: Permission.Codec },
+    R,
+  >(
+    permission: Permission.Tag<PermissionSelf, I, D, R>,
+  ): PermissionFilter<Self, D, R> => {
+    const key = `${permission.key}/Filter`;
+    const Tag = Context.Service<Self, Api<D, R>>()(key);
+
+    const toLayer: Statics<Self, D, R>["toLayer"] = (policy) =>
+      Layer.effect(
+        Tag,
+        Effect.gen(function* () {
+          const resolved = Effect.isEffect(policy) ? yield* policy : policy;
+
+          const condition = Effect.gen(function* () {
+            const refused = yield* Permission.isRestricted(permission);
+
+            if (refused) return Condition.make<Permission.TargetOf<D>>().none();
+
+            const result = resolved(Condition.make());
+
+            return Effect.isEffect(result) ? yield* result : result;
+          }).pipe(
+            Effect.tap((result) =>
+              Effect.annotateCurrentSpan({
+                "access.permission": permission.id,
+                "access.condition": result._tag,
+              }),
+            ),
+            Effect.withSpan(`${key}.condition`),
+          );
+
+          return Tag.of({ condition });
+        }),
+      );
+
+    return Object.assign(Tag, {
+      condition: Tag.use((filter) => filter.condition),
+      toLayer,
+    });
+  };

package/src/audit.ts

@@ -0,0 +1,82 @@
+import * as Audit from "@kutur-kit/audit/Audit";
+import * as AuditEvent from "@kutur-kit/audit/AuditEvent";
+import { Effect, Layer, Predicate, Schema } from "effect";
+
+import * as Permission from "./Permission.ts";
+
+/** What refused a denied decision. Allowed decisions have no details. */
+export const Details = Schema.UndefinedOr(
+  Schema.Struct({
+    deniedBy: Schema.Literals(["restriction", "policy", "requirement"]),
+    requirement: Schema.optionalKey(Schema.String),
+  }),
+);
+
+type CheckView<D extends Permission.Definition, V> = [V] extends [never]
+  ? unknown
+  : [V] extends [Permission.Codec]
+    ? D extends { readonly target: Permission.Codec }
+      ? [Permission.TargetOf<D>] extends [V["Type"]]
+        ? unknown
+        : { readonly view: Schema.Codec<Permission.TargetOf<D>, unknown> }
+      : { readonly view?: false }
+    : unknown;
+
+export interface Options<V> {
+  /** See `AuditEvent.Definition["view"]`. */
+  readonly view?: V;
+}
+
+/**
+ * Records the decisions of a permission's `require`s as audit events named by
+ * its id; `check`s only answer questions, so they are not recorded. Refusals
+ * fail the request whose transaction would store them, so writes are isolated.
+ */
+export const record = <
+  Self,
+  I extends string,
+  D extends Permission.Definition,
+  R,
+  const V extends Permission.Codec | false = never,
+>(
+  permission: Permission.Tag<Self, I, D, R>,
+  options?: Options<V> & CheckView<D, V>,
+) => {
+  const view = options?.view;
+
+  // Permissions without a target log Schema.Undefined, which records nothing.
+  const event = AuditEvent.make(permission.id, {
+    target: permission.definition.target ?? Schema.Undefined,
+    ...(view !== undefined && { view }),
+    outcomes: ["Allow", "Deny"] as const,
+    details: Details,
+    isolated: true,
+  });
+
+  return <E, RL>(layer: Layer.Layer<Self, E, RL>): Layer.Layer<Self, E, RL | Audit.AuditLog> =>
+    Layer.effect(
+      permission,
+      Effect.gen(function* () {
+        const inner = yield* permission;
+        const auditLog = yield* Audit.AuditLog;
+
+        return Permission.tap<D>(({ via, target: args, decision }) => {
+          if (via === "check") return Effect.void;
+
+          const denied = Predicate.isTagged(decision, "Deny") ? decision : undefined;
+
+          return event
+            .log({
+              target: args[0],
+              outcome: decision._tag,
+              ...(denied?.reason !== undefined && { reason: denied.reason }),
+              details: denied && {
+                deniedBy: denied.by,
+                ...(denied.requirement !== undefined && { requirement: denied.requirement }),
+              },
+            })
+            .pipe(Effect.provideService(Audit.AuditLog, auditLog));
+        })(inner);
+      }),
+    ).pipe(Layer.provide(layer));
+};