jurist 0.0.0

package/README.md

@@ -0,0 +1,71 @@
+# jurist
+
+```sh
+npm i jurist
+```
+
+Jurist is a TypeScript-first authorization library supporting role-based access control.
+
+## usage
+
+### `Laws`
+
+With Jurist, permissions are expressed in a tree structure.
+
+```typescript
+// my-authorization.ts
+import { Laws, optional, required } from "jurist";
+
+const authorization = new Laws({
+  roles: ["suspended", "free", "premium"],
+  permissions: required({
+    create: optional({
+      document: required({
+        "<=5": optional({ "<=5000": null }),
+        shareDocuments: null,
+      }),
+    }),
+  }),
+  rolePermissions: {
+    suspended: new Set([]),
+    free: new Set([
+      /* a granted  permission grants all preceding permissions, e.g., 
+      "create"
+      "create_documents" */
+      "create_documents_<=5",
+    ]),
+    premium: new Set([
+      "create_documents_<=5_<=5000",
+      "create_documents_shareDocuments",
+    ]),
+  },
+});
+```
+
+The idea here is that some permissions must logically follow from other permissions. In other words, the `create_documents_<=5` permission is a prerequisite for the `create_documents_<=5_<=5000` permission, because if you are allowed to create 5,000 documents, you are logically allowed to create 5 documents in the first place.
+
+This makes authorization checks easier, safer, and more explicit.
+
+```typescript
+// routes.ts
+import { Roles } from "jurist";
+
+import { authorization } from "./my-authorization";
+import { app } from "./my-hono-like-app";
+
+type Role = Roles<typeof authorization>; // "free" | "premium" | "suspended"
+
+type User = {
+  id: string;
+  role: Role;
+};
+
+app.post("/api/v1/resources", async (c) => {
+  const { user /* { id: "123-456", role: "free" } */ } = c.get("user");
+  /* ✅ true  */ authorization.check(user.role, "create");
+  /* ✅ true  */ authorization.check(user.role, "create_documents_<=5");
+  /* ❌ false */ authorization.check(user.role, "create_documents_<=5_<=5000");
+});
+```
+
+Here, we can see that a free user has permission to create a resource, and has permission to own up to 5 documents, but they cannot own up to 5,000 documents like a premium user.

package/dist/jurist.d.ts

@@ -0,0 +1,43 @@
+import { Tree, Join, TreePathName } from 'treetrunks';
+export * from 'treetrunks';
+
+type Roles<L extends Laws<any, any, any, any>> = L extends Laws<infer Role, any, any, any> ? Role : never;
+type Permissions<L extends Laws<any, any, any, any>> = L extends Laws<any, any, infer Permission, any> ? Permission : never;
+type PermissionData<L extends Laws<any, any, any, any>, D> = Entries<Permissions<L>, D>;
+declare class Laws<Role extends string, PermissionTree extends Tree, Permission extends Join<TreePathName<PermissionTree>, `_`>, RolePermissions extends {
+    [r in Role]: ReadonlySet<Permission>;
+}> {
+    readonly roles: Role[];
+    readonly permissionTree: PermissionTree;
+    readonly rolePermissions: RolePermissions;
+    protected readonly decompressedRolePermissions: {
+        [r in Role]: ReadonlySet<string>;
+    };
+    constructor(options: {
+        roles: Role[];
+        permissions: PermissionTree;
+        rolePermissions: RolePermissions;
+    });
+    check(role: Role, permission: Permission): boolean;
+}
+type EscalatorStyle = `firstFound` | `lastFound` | `untilMiss`;
+declare class Escalator<S extends EscalatorStyle, L extends Laws<any, any, any, any>, P extends PermissionData<L, any>, D extends P extends PermissionData<L, infer d> ? d : never, F> {
+    readonly style: S;
+    readonly laws: L;
+    readonly permissionData: P;
+    readonly fallback: F;
+    constructor(options: Readonly<{
+        style: S;
+        laws: L;
+        permissionData: P;
+        fallback: F;
+    }>);
+    get(role: Roles<L>): D | F;
+}
+type Count<N extends number, A extends any[] = []> = [
+    ...A,
+    any
+][`length`] extends N ? A[`length`] : A[`length`] | Count<N, [...A, any]>;
+type Entries<K extends PropertyKey = keyof any, V = any> = [K, V][];
+
+export { type Count, Escalator, type EscalatorStyle, Laws, type PermissionData, type Permissions, type Roles };

package/dist/jurist.js

@@ -0,0 +1,78 @@
+export * from 'treetrunks';
+
+// src/jurist.ts
+var Laws = class {
+  roles;
+  permissionTree;
+  rolePermissions;
+  decompressedRolePermissions;
+  constructor(options) {
+    const { roles, permissions, rolePermissions } = options;
+    this.roles = roles;
+    this.permissionTree = permissions;
+    this.rolePermissions = rolePermissions;
+    this.decompressedRolePermissions = fromEntries(
+      toEntries(rolePermissions).map(
+        ([role, permissionsOfRole]) => [
+          role,
+          decompressRolePermissions(permissionsOfRole)
+        ]
+      )
+    );
+  }
+  check(role, permission) {
+    return this.decompressedRolePermissions[role].has(permission);
+  }
+};
+function decompressRolePermissions(permissionSet) {
+  const decompressed = new Set(permissionSet);
+  for (const permission of permissionSet) {
+    const preconditions = permission.split(`_`);
+    for (let i = 0; i < preconditions.length - 1; i++) {
+      const subPermission = preconditions.slice(0, i + 1).join(`_`);
+      decompressed.add(subPermission);
+    }
+  }
+  return decompressed;
+}
+var Escalator = class {
+  style;
+  laws;
+  permissionData;
+  fallback;
+  constructor(options) {
+    const { style, laws, permissionData, fallback } = options;
+    this.style = style;
+    this.laws = laws;
+    this.permissionData = permissionData;
+    this.fallback = fallback;
+  }
+  get(role) {
+    let result = this.fallback;
+    for (const [permission, data] of this.permissionData) {
+      const hasPermission = this.laws.check(role, permission);
+      switch (this.style) {
+        case `firstFound`:
+          if (hasPermission) return data;
+          break;
+        case `lastFound`:
+          if (hasPermission) result = data;
+          break;
+        case `untilMiss`:
+          if (hasPermission) result = data;
+          else return result;
+      }
+    }
+    return result;
+  }
+};
+function fromEntries(entries) {
+  return Object.fromEntries(entries);
+}
+function toEntries(obj) {
+  return Object.entries(obj);
+}
+
+export { Escalator, Laws };
+//# sourceMappingURL=jurist.js.map
+//# sourceMappingURL=jurist.js.map

package/dist/jurist.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/jurist.ts"],"names":[],"mappings":";;;AA2BO,IAAM,OAAN,MAKL;AAAA,EACe,KAAA;AAAA,EACA,cAAA;AAAA,EACA,eAAA;AAAA,EACG,2BAAA;AAAA,EAIZ,YAAY,OAIhB,EAAA;AACF,IAAA,MAAM,EAAE,KAAA,EAAO,WAAa,EAAA,eAAA,EAAoB,GAAA,OAAA;AAChD,IAAA,IAAA,CAAK,KAAQ,GAAA,KAAA;AACb,IAAA,IAAA,CAAK,cAAiB,GAAA,WAAA;AACtB,IAAA,IAAA,CAAK,eAAkB,GAAA,eAAA;AACvB,IAAA,IAAA,CAAK,2BAA8B,GAAA,WAAA;AAAA,MAClC,SAAA,CAA2B,eAAe,CAAE,CAAA,GAAA;AAAA,QAC3C,CAAC,CAAC,IAAM,EAAA,iBAAiB,CAAM,KAAA;AAAA,UAC9B,IAAA;AAAA,UACA,0BAA0B,iBAAiB;AAAA;AAC5C;AACD,KACD;AAAA;AACD,EAEO,KAAA,CAAM,MAAY,UAAiC,EAAA;AACzD,IAAA,OAAO,IAAK,CAAA,2BAAA,CAA4B,IAAI,CAAA,CAAE,IAAI,UAAU,CAAA;AAAA;AAE9D;AAEA,SAAS,0BACR,aACsB,EAAA;AACtB,EAAM,MAAA,YAAA,GAAe,IAAI,GAAA,CAAY,aAAa,CAAA;AAClD,EAAA,KAAA,MAAW,cAAc,aAAe,EAAA;AACvC,IAAM,MAAA,aAAA,GAAgB,UAAW,CAAA,KAAA,CAAM,CAAG,CAAA,CAAA,CAAA;AAC1C,IAAA,KAAA,IAAS,IAAI,CAAG,EAAA,CAAA,GAAI,aAAc,CAAA,MAAA,GAAS,GAAG,CAAK,EAAA,EAAA;AAClD,MAAM,MAAA,aAAA,GAAgB,cAAc,KAAM,CAAA,CAAA,EAAG,IAAI,CAAC,CAAA,CAAE,KAAK,CAAG,CAAA,CAAA,CAAA;AAC5D,MAAA,YAAA,CAAa,IAAI,aAAa,CAAA;AAAA;AAC/B;AAED,EAAO,OAAA,YAAA;AACR;AAGO,IAAM,YAAN,MAML;AAAA,EACe,KAAA;AAAA,EACA,IAAA;AAAA,EACA,cAAA;AAAA,EACA,QAAA;AAAA,EACT,YACN,OAMC,EAAA;AACD,IAAA,MAAM,EAAE,KAAA,EAAO,IAAM,EAAA,cAAA,EAAgB,UAAa,GAAA,OAAA;AAClD,IAAA,IAAA,CAAK,KAAQ,GAAA,KAAA;AACb,IAAA,IAAA,CAAK,IAAO,GAAA,IAAA;AACZ,IAAA,IAAA,CAAK,cAAiB,GAAA,cAAA;AACtB,IAAA,IAAA,CAAK,QAAW,GAAA,QAAA;AAAA;AACjB,EAEO,IAAI,IAAuB,EAAA;AACjC,IAAA,IAAI,SAAgB,IAAK,CAAA,QAAA;AACzB,IAAA,KAAA,MAAW,CAAC,UAAA,EAAY,IAAI,CAAA,IAAK,KAAK,cAAgB,EAAA;AACrD,MAAA,MAAM,aAAgB,GAAA,IAAA,CAAK,IAAK,CAAA,KAAA,CAAM,MAAM,UAAU,CAAA;AACtD,MAAA,QAAQ,KAAK,KAAO;AAAA,QACnB,KAAK,CAAA,UAAA,CAAA;AACJ,UAAA,IAAI,eAAsB,OAAA,IAAA;AAC1B,UAAA;AAAA,QACD,KAAK,CAAA,SAAA,CAAA;AACJ,UAAA,IAAI,eAAwB,MAAA,GAAA,IAAA;AAC5B,UAAA;AAAA,QACD,KAAK,CAAA,SAAA,CAAA;AACJ,UAAA,IAAI,eAAwB,MAAA,GAAA,IAAA;AAAA,eAChB,OAAA,MAAA;AAAA;AACd;AAED,IAAO,OAAA,MAAA;AAAA;AAET;AAyBA,SAAS,YAA+B,OAA4B,EAAA;AACnE,EAAO,OAAA,MAAA,CAAO,YAAY,OAAO,CAAA;AAClC;AAEA,SAAS,UAA4B,GAAsC,EAAA;AAC1E,EAAO,OAAA,MAAA,CAAO,QAAQ,GAAG,CAAA;AAC1B","file":"jurist.js","sourcesContent":["import type { Join, Tree, TreePathName } from \"treetrunks\"\n\nexport * from \"treetrunks\"\n\nexport type Roles<L extends Laws<any, any, any, any>> = L extends Laws<\n\tinfer Role,\n\tany,\n\tany,\n\tany\n>\n\t? Role\n\t: never\n\nexport type Permissions<L extends Laws<any, any, any, any>> = L extends Laws<\n\tany,\n\tany,\n\tinfer Permission,\n\tany\n>\n\t? Permission\n\t: never\n\nexport type PermissionData<L extends Laws<any, any, any, any>, D> = Entries<\n\tPermissions<L>,\n\tD\n>\n\nexport class Laws<\n\tRole extends string,\n\tPermissionTree extends Tree,\n\tPermission extends Join<TreePathName<PermissionTree>, `_`>,\n\tRolePermissions extends { [r in Role]: ReadonlySet<Permission> },\n> {\n\tpublic readonly roles: Role[]\n\tpublic readonly permissionTree: PermissionTree\n\tpublic readonly rolePermissions: RolePermissions\n\tprotected readonly decompressedRolePermissions: {\n\t\t[r in Role]: ReadonlySet<string>\n\t}\n\n\tpublic constructor(options: {\n\t\troles: Role[]\n\t\tpermissions: PermissionTree\n\t\trolePermissions: RolePermissions\n\t}) {\n\t\tconst { roles, permissions, rolePermissions } = options\n\t\tthis.roles = roles\n\t\tthis.permissionTree = permissions\n\t\tthis.rolePermissions = rolePermissions\n\t\tthis.decompressedRolePermissions = fromEntries(\n\t\t\ttoEntries<RolePermissions>(rolePermissions).map(\n\t\t\t\t([role, permissionsOfRole]) => [\n\t\t\t\t\trole,\n\t\t\t\t\tdecompressRolePermissions(permissionsOfRole),\n\t\t\t\t],\n\t\t\t),\n\t\t)\n\t}\n\n\tpublic check(role: Role, permission: Permission): boolean {\n\t\treturn this.decompressedRolePermissions[role].has(permission)\n\t}\n}\n\nfunction decompressRolePermissions(\n\tpermissionSet: ReadonlySet<string>,\n): ReadonlySet<string> {\n\tconst decompressed = new Set<string>(permissionSet)\n\tfor (const permission of permissionSet) {\n\t\tconst preconditions = permission.split(`_`)\n\t\tfor (let i = 0; i < preconditions.length - 1; i++) {\n\t\t\tconst subPermission = preconditions.slice(0, i + 1).join(`_`)\n\t\t\tdecompressed.add(subPermission)\n\t\t}\n\t}\n\treturn decompressed\n}\n\nexport type EscalatorStyle = `firstFound` | `lastFound` | `untilMiss`\nexport class Escalator<\n\tS extends EscalatorStyle,\n\tL extends Laws<any, any, any, any>,\n\tP extends PermissionData<L, any>,\n\tD extends P extends PermissionData<L, infer d> ? d : never,\n\tF,\n> {\n\tpublic readonly style: S\n\tpublic readonly laws: L\n\tpublic readonly permissionData: P\n\tpublic readonly fallback: F\n\tpublic constructor(\n\t\toptions: Readonly<{\n\t\t\tstyle: S\n\t\t\tlaws: L\n\t\t\tpermissionData: P\n\t\t\tfallback: F\n\t\t}>,\n\t) {\n\t\tconst { style, laws, permissionData, fallback } = options\n\t\tthis.style = style\n\t\tthis.laws = laws\n\t\tthis.permissionData = permissionData\n\t\tthis.fallback = fallback\n\t}\n\n\tpublic get(role: Roles<L>): D | F {\n\t\tlet result: D | F = this.fallback\n\t\tfor (const [permission, data] of this.permissionData) {\n\t\t\tconst hasPermission = this.laws.check(role, permission)\n\t\t\tswitch (this.style) {\n\t\t\t\tcase `firstFound`:\n\t\t\t\t\tif (hasPermission) return data\n\t\t\t\t\tbreak\n\t\t\t\tcase `lastFound`:\n\t\t\t\t\tif (hasPermission) result = data\n\t\t\t\t\tbreak\n\t\t\t\tcase `untilMiss`:\n\t\t\t\t\tif (hasPermission) result = data\n\t\t\t\t\telse return result\n\t\t\t}\n\t\t}\n\t\treturn result\n\t}\n}\n\ntype Flat<R extends { [K in PropertyKey]: any }> = {\n\t[K in keyof R]: R[K]\n}\n\nexport type Count<N extends number, A extends any[] = []> = [\n\t...A,\n\tany,\n][`length`] extends N\n\t? A[`length`]\n\t: A[`length`] | Count<N, [...A, any]>\n\ntype Entries<K extends PropertyKey = keyof any, V = any> = [K, V][]\n\ntype KeyOfEntries<E extends Entries> = E extends [infer K, any][] ? K : never\n\ntype ValueOfEntry<E extends Entries, K extends KeyOfEntries<E>> = {\n\t[P in Count<E[`length`]>]: E[P] extends [K, infer V] ? V : never\n}[Count<E[`length`]>]\n\ntype FromEntries<E extends Entries> = Flat<{\n\t[K in KeyOfEntries<E>]: ValueOfEntry<E, K>\n}>\n\nfunction fromEntries<E extends Entries>(entries: E): FromEntries<E> {\n\treturn Object.fromEntries(entries) as FromEntries<E>\n}\n\nfunction toEntries<T extends object>(obj: T): Entries<keyof T, T[keyof T]> {\n\treturn Object.entries(obj) as Entries<keyof T, T[keyof T]>\n}\n"]}

package/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "jurist",
+	"version": "0.0.0",
+	"license": "MIT",
+	"author": {
+		"name": "Jeremy Banka",
+		"email": "hello@jeremybanka.com"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/jeremybanka/wayforge.git",
+		"directory": "packages/jurist"
+	},
+	"type": "module",
+	"files": ["dist", "src"],
+	"main": "dist/jurist.js",
+	"scripts": {
+		"build": "tsup-node",
+		"lint:biome": "biome check -- .",
+		"lint:eslint": "eslint -- .",
+		"lint:types": "tsc --noEmit",
+		"watch:types": "tsc --watch --noEmit",
+		"lint": "concurrently \"bun:lint:*\"",
+		"test": "vitest",
+		"test:once": "vitest run",
+		"postversion": "biome format --write package.json"
+	},
+	"dependencies": {
+		"treetrunks": "workspace:*"
+	},
+	"devDependencies": {
+		"concurrently": "9.1.2",
+		"eslint": "9.21.0",
+		"rimraf": "6.0.1",
+		"tsup": "8.4.0",
+		"vitest": "3.0.7"
+	}
+}

package/src/jurist.ts

@@ -0,0 +1,155 @@
+import type { Join, Tree, TreePathName } from "treetrunks"
+
+export * from "treetrunks"
+
+export type Roles<L extends Laws<any, any, any, any>> = L extends Laws<
+	infer Role,
+	any,
+	any,
+	any
+>
+	? Role
+	: never
+
+export type Permissions<L extends Laws<any, any, any, any>> = L extends Laws<
+	any,
+	any,
+	infer Permission,
+	any
+>
+	? Permission
+	: never
+
+export type PermissionData<L extends Laws<any, any, any, any>, D> = Entries<
+	Permissions<L>,
+	D
+>
+
+export class Laws<
+	Role extends string,
+	PermissionTree extends Tree,
+	Permission extends Join<TreePathName<PermissionTree>, `_`>,
+	RolePermissions extends { [r in Role]: ReadonlySet<Permission> },
+> {
+	public readonly roles: Role[]
+	public readonly permissionTree: PermissionTree
+	public readonly rolePermissions: RolePermissions
+	protected readonly decompressedRolePermissions: {
+		[r in Role]: ReadonlySet<string>
+	}
+
+	public constructor(options: {
+		roles: Role[]
+		permissions: PermissionTree
+		rolePermissions: RolePermissions
+	}) {
+		const { roles, permissions, rolePermissions } = options
+		this.roles = roles
+		this.permissionTree = permissions
+		this.rolePermissions = rolePermissions
+		this.decompressedRolePermissions = fromEntries(
+			toEntries<RolePermissions>(rolePermissions).map(
+				([role, permissionsOfRole]) => [
+					role,
+					decompressRolePermissions(permissionsOfRole),
+				],
+			),
+		)
+	}
+
+	public check(role: Role, permission: Permission): boolean {
+		return this.decompressedRolePermissions[role].has(permission)
+	}
+}
+
+function decompressRolePermissions(
+	permissionSet: ReadonlySet<string>,
+): ReadonlySet<string> {
+	const decompressed = new Set<string>(permissionSet)
+	for (const permission of permissionSet) {
+		const preconditions = permission.split(`_`)
+		for (let i = 0; i < preconditions.length - 1; i++) {
+			const subPermission = preconditions.slice(0, i + 1).join(`_`)
+			decompressed.add(subPermission)
+		}
+	}
+	return decompressed
+}
+
+export type EscalatorStyle = `firstFound` | `lastFound` | `untilMiss`
+export class Escalator<
+	S extends EscalatorStyle,
+	L extends Laws<any, any, any, any>,
+	P extends PermissionData<L, any>,
+	D extends P extends PermissionData<L, infer d> ? d : never,
+	F,
+> {
+	public readonly style: S
+	public readonly laws: L
+	public readonly permissionData: P
+	public readonly fallback: F
+	public constructor(
+		options: Readonly<{
+			style: S
+			laws: L
+			permissionData: P
+			fallback: F
+		}>,
+	) {
+		const { style, laws, permissionData, fallback } = options
+		this.style = style
+		this.laws = laws
+		this.permissionData = permissionData
+		this.fallback = fallback
+	}
+
+	public get(role: Roles<L>): D | F {
+		let result: D | F = this.fallback
+		for (const [permission, data] of this.permissionData) {
+			const hasPermission = this.laws.check(role, permission)
+			switch (this.style) {
+				case `firstFound`:
+					if (hasPermission) return data
+					break
+				case `lastFound`:
+					if (hasPermission) result = data
+					break
+				case `untilMiss`:
+					if (hasPermission) result = data
+					else return result
+			}
+		}
+		return result
+	}
+}
+
+type Flat<R extends { [K in PropertyKey]: any }> = {
+	[K in keyof R]: R[K]
+}
+
+export type Count<N extends number, A extends any[] = []> = [
+	...A,
+	any,
+][`length`] extends N
+	? A[`length`]
+	: A[`length`] | Count<N, [...A, any]>
+
+type Entries<K extends PropertyKey = keyof any, V = any> = [K, V][]
+
+type KeyOfEntries<E extends Entries> = E extends [infer K, any][] ? K : never
+
+type ValueOfEntry<E extends Entries, K extends KeyOfEntries<E>> = {
+	[P in Count<E[`length`]>]: E[P] extends [K, infer V] ? V : never
+}[Count<E[`length`]>]
+
+type FromEntries<E extends Entries> = Flat<{
+	[K in KeyOfEntries<E>]: ValueOfEntry<E, K>
+}>
+
+function fromEntries<E extends Entries>(entries: E): FromEntries<E> {
+	return Object.fromEntries(entries) as FromEntries<E>
+}
+
+function toEntries<T extends object>(obj: T): Entries<keyof T, T[keyof T]> {
+	return Object.entries(obj) as Entries<keyof T, T[keyof T]>
+}