@typed-policy/core 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Togle Labs <m.ihsan.vp@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,281 @@
+type Primitive = string | number | boolean | null | undefined;
+type Path<T> = T extends Primitive ? never : {
+    [K in keyof T & string]: T[K] extends Primitive ? K : K | `${K}.${Path<T[K]>}`;
+}[keyof T & string];
+
+type PathValue<T, P extends Path<T>> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? PathValue<T[K], Extract<Rest, Path<T[K]>>> : never : P extends keyof T ? T[P] : never;
+type PolicyContext = {
+    user: {
+        id: string;
+        role: "admin" | "user";
+    };
+    post: {
+        id: string;
+        ownerId: string;
+        published: boolean;
+    };
+};
+
+/**
+ * Expression AST type
+ *
+ * T = Subject context type (paths reference this)
+ * A = Actor context type (available to functions)
+ *
+ * @example
+ * type MyExpr = Expr<{ post: { published: boolean } }, { user: { role: string } }>;
+ */
+type Expr<T, A = unknown> = {
+    kind: "eq";
+    left: Path<T>;
+    right: Path<T> | PathValue<T, Path<T>>;
+} | {
+    kind: "and";
+    rules: Expr<T, A>[];
+} | {
+    kind: "or";
+    rules: Expr<T, A>[];
+} | {
+    kind: "literal";
+    value: boolean;
+} | {
+    kind: "function";
+    fn: (ctx: {
+        actor: A;
+    }) => boolean | Expr<T, A>;
+    description?: string;
+};
+
+/**
+ * Context types for Typed Policy v0.2
+ *
+ * Separates actor (user/requester) from subject (resource)
+ * for better authorization modeling.
+ */
+/**
+ * Actor context - represents the user or entity making the request
+ * Developers define their own actor shape based on their application
+ *
+ * @example
+ * type MyActor = {
+ *   user: {
+ *     id: string;
+ *     role: "admin" | "user" | "moderator";
+ *     organizationId: string;
+ *   };
+ * };
+ */
+type ActorContext = {
+    user: {
+        id: string;
+        role: "admin" | "user";
+    };
+};
+/**
+ * Subject context - represents the resource being accessed
+ * Developers define their own subject shape based on their data model
+ *
+ * @example
+ * type MySubject = {
+ *   post: {
+ *     id: string;
+ *     ownerId: string;
+ *     published: boolean;
+ *     organizationId: string;
+ *   };
+ * };
+ */
+type SubjectContext = {
+    post: {
+        id: string;
+        ownerId: string;
+        published: boolean;
+    };
+};
+/**
+ * Full context combining actor and subject
+ * Used internally but developers typically use separate Actor/Subject types
+ */
+type FullContext<A, S> = A & S;
+/**
+ * Evaluation context passed to policy functions
+ * Functions ONLY receive actor - subject is accessed through DSL (eq, and, or)
+ * This ensures consistency between frontend and backend evaluation
+ */
+type EvalContext<A> = {
+    /** The actor (user) making the request */
+    actor: A;
+};
+/**
+ * Resource mapping for nested resource structure in evaluate
+ * Maps resource types to their property types
+ *
+ * @example
+ * type PostMapping = ResourceMapping<{
+ *   post: { id: string; ownerId: string; published: boolean };
+ * }>;
+ * // Results in: { post: { id: string; ownerId: string; published: boolean } }
+ */
+type ResourceMapping<T> = {
+    [K in keyof T]: {
+        [P in keyof T[K]]: T[K][P];
+    };
+};
+
+/**
+ * Equality comparison operator
+ * Compares a subject path to a value or another path
+ *
+ * @example
+ * eq("post.published", true)
+ * eq("post.ownerId", "user.id")
+ */
+declare function eq<T, L extends Path<T>, A = unknown>(left: L, right: Path<T> | PathValue<T, L>): Expr<T, A>;
+/**
+ * Logical AND operator
+ * All rules must be true
+ *
+ * @example
+ * and(eq("post.published", true), eq("user.role", "admin"))
+ */
+declare function and<T, A = unknown>(...rules: Expr<T, A>[]): Expr<T, A>;
+/**
+ * Logical OR operator
+ * At least one rule must be true
+ *
+ * @example
+ * or(eq("user.role", "admin"), eq("post.published", true))
+ */
+declare function or<T, A = unknown>(...rules: Expr<T, A>[]): Expr<T, A>;
+
+/**
+ * Policy configuration with separate actor and subject types
+ *
+ * A = Actor context type (the user/requester)
+ * S = Subject context type (the resource being accessed)
+ *
+ * Functions ONLY receive actor - subject is accessed through DSL:
+ * @example
+ * const policy = policy<MyActor, MySubject>({
+ *   subject: "Post",
+ *   actions: {
+ *     // Function: only actor available
+ *     read: ({ actor }) => {
+ *       if (actor.user.role === "admin") return true;
+ *       return eq("post.published", true); // Subject via DSL
+ *     },
+ *     // Boolean literal
+ *     create: true,
+ *     // Declarative DSL
+ *     delete: eq("post.ownerId", "user.id")
+ *   }
+ * });
+ */
+interface PolicyConfig<A, S> {
+    subject: string;
+    actions: {
+        [K: string]: Expr<S, A> | boolean | ((ctx: EvalContext<A>) => boolean | Expr<S, A>);
+    };
+}
+/**
+ * Define a policy with type-safe actor and subject contexts
+ *
+ * Actions can be:
+ * - Functions: ({ actor }) => boolean | Expr  (actor only!)
+ * - Declarative: eq("post.published", true)  (subject via DSL)
+ * - Literals: true, false
+ */
+declare function policy<A, S>(config: PolicyConfig<A, S>): PolicyConfig<A, S>;
+
+/**
+ * Converts a union type to an intersection type
+ * Uses distributive conditional types trick
+ */
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Extracts all subject paths used in an expression
+ * This traverses the expression AST and collects all paths that reference the subject (T)
+ */
+type ExprPaths<T, A, E extends Expr<T, A>> = E extends {
+    kind: "eq";
+    left: infer L extends Path<T>;
+    right: infer R;
+} ? R extends Path<T> ? L | R : L : E extends {
+    kind: "and" | "or";
+    rules: infer Rules extends readonly Expr<T, A>[];
+} ? Rules extends readonly [infer First, ...infer Rest] ? First extends Expr<T, A> ? Rest extends readonly Expr<T, A>[] ? ExprPaths<T, A, First> | ExprPathsMany<T, A, Rest> : ExprPaths<T, A, First> : never : never : never;
+/**
+ * Helper type to extract paths from multiple expressions
+ */
+type ExprPathsMany<T, A, Rules extends readonly Expr<T, A>[]> = Rules extends readonly [
+    infer First,
+    ...infer Rest
+] ? First extends Expr<T, A> ? Rest extends readonly Expr<T, A>[] ? ExprPaths<T, A, First> | ExprPathsMany<T, A, Rest> : ExprPaths<T, A, First> : never : never;
+/**
+ * DeepPick - picks nested properties from an object type using dot-notation paths
+ * Similar to a deep version of TypeScript's built-in Pick
+ *
+ * @example
+ * type Obj = { post: { published: boolean; title: string } };
+ * type Picked = DeepPick<Obj, "post.published">; // { post: { published: boolean } }
+ */
+type DeepPick<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? {
+    [Key in K]: DeepPick<T[K], Rest>;
+} : never : P extends keyof T ? {
+    [Key in P]: T[Key];
+} : never;
+/**
+ * Builds minimal context containing only the paths referenced in an expression
+ * This allows creating a subset of the full context with only what's needed
+ *
+ * @example
+ * type Full = { post: { published: boolean; title: string } };
+ * type Minimal = MinimalContext<Full, "post.published">;
+ * // Result: { post: { published: boolean } }
+ */
+type MinimalContext<T, P extends Path<T>> = UnionToIntersection<DeepPick<T, P>>;
+/**
+ * Infers the minimal subject context type required for an expression
+ * Only includes the paths that are actually referenced in the expression
+ *
+ * @example
+ * type MySubject = { post: { published: boolean; title: string } };
+ * type MyActor = { user: { id: string } };
+ * type MyExpr = Expr<MySubject, MyActor>; // eq("post.published", true)
+ * type Subject = InferSubjectContext<MySubject, MyActor, MyExpr>;
+ * // Result: { post: { published: boolean } }
+ */
+type InferSubjectContext<T, A, E extends Expr<T, A>> = ExprPaths<T, A, E> extends Path<T> ? UnionToIntersection<DeepPick<T, ExprPaths<T, A, E>>> : T;
+/**
+ * Infers the actor context type from an expression
+ * The actor context is passed to function expressions and contains user/requester data
+ *
+ * @example
+ * type MyActor = { user: { id: string; role: string } };
+ * type MySubject = { post: { published: boolean } };
+ * type MyExpr = Expr<MySubject, MyActor>;
+ * type Actor = InferActorContext<MySubject, MyActor, MyExpr>;
+ * // Result: { user: { id: string; role: string } }
+ */
+type InferActorContext<T, A, _E extends Expr<T, A>> = A;
+
+/**
+ * Error message utilities for Typed Policy
+ *
+ * Provides consistent error messages for common failure scenarios.
+ */
+/**
+ * Creates a standardized error message for missing context paths
+ *
+ * @param missingPath - The path that was not found in the context
+ * @returns A formatted error message string
+ *
+ * @example
+ * ```ts
+ * throw new Error(createContextError("user.role"));
+ * // throws: Missing required context path: "user.role"
+ * ```
+ */
+declare function createContextError(missingPath: string): string;
+
+export { type ActorContext, type DeepPick, type EvalContext, type Expr, type ExprPaths, type FullContext, type InferActorContext, type InferSubjectContext, type MinimalContext, type Path, type PathValue, type PolicyConfig, type PolicyContext, type Primitive, type ResourceMapping, type SubjectContext, type UnionToIntersection, and, createContextError, eq, or, policy };

package/dist/index.js

@@ -0,0 +1,27 @@
+// src/operators.ts
+function eq(left, right) {
+  return { kind: "eq", left, right };
+}
+function and(...rules) {
+  return { kind: "and", rules };
+}
+function or(...rules) {
+  return { kind: "or", rules };
+}
+
+// src/policy.ts
+function policy(config) {
+  return config;
+}
+
+// src/errors.ts
+function createContextError(missingPath) {
+  return `Missing required context path: "${missingPath}"`;
+}
+export {
+  and,
+  createContextError,
+  eq,
+  or,
+  policy
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@typed-policy/core",
+  "version": "0.2.0",
+  "description": "Core types and DSL for typed policies",
+  "author": "Ihsan VP <m.ihsan.vp@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/toglelabs/typed-policy.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/toglelabs/typed-policy/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/toglelabs/typed-policy/issues"
+  },
+  "keywords": [
+    "typescript",
+    "policy",
+    "authorization",
+    "type-safe",
+    "dsl",
+    "ast"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "typescript": "^5.7.0",
+    "tsup": "^8.3.0"
+  },
+  "peerDependencies": {},
+  "dependencies": {},
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "lint": "biome check src",
+    "format": "biome format --write src"
+  }
+}