📖 Add comprehensive KSL tutorial system with 4-file learning path

tutorials/01_complete_basic_syntax.ksl

@@ -0,0 +1,55 @@
+version 0.1
+namespace learning
+
+// Basic type with no relations
+public type user {
+
+}
+
+// Type demonstrating ALL cardinality constraints
+public type document {
+    // ExactlyOne - must have exactly one
+    relation owner: [ExactlyOne user]
+
+    // Any - can have zero, one, or unlimited
+    relation editor: [Any user]
+
+    // AtMostOne - can have zero or one
+    relation reviewer: [AtMostOne user]
+
+    // AtLeastOne - must have one or more
+    relation approver: [AtLeastOne user]
+
+    // Basic permission - direct reference
+    relation can_read: owner
+
+    // Union (OR) - multiple ways to get permission
+    relation can_edit: owner or editor
+
+    // Complex union - three ways to get permission
+    relation can_view: owner or editor or reviewer
+
+    // Intersection (AND) - must satisfy both conditions
+    relation can_approve: approver and owner
+
+    // Exclusion (UNLESS) - first condition unless second is true
+    relation can_delete: owner unless reviewer
+
+    // Grouping with parentheses for complex logic
+    relation can_publish: (owner or editor) and approver
+}
+
+// Demonstrating ALL visibility modifiers
+public type project {
+    // Public - accessible from other namespaces
+    public relation owner: [ExactlyOne user]
+
+    // Internal - accessible within this namespace only
+    internal relation team_member: [Any user]
+
+    // Private - accessible within this type only
+    private relation secret_info: [Any user]
+
+    // Default visibility (public if not specified)
+    relation contributor: [Any user]
+}

tutorials/01_complete_basic_syntax.zed

@@ -0,0 +1,29 @@
+definition learning/document {
+	permission approver = t_approver
+	relation t_approver: learning/user
+	permission can_approve = (approver & owner)
+	permission can_delete = (owner - reviewer)
+	permission can_edit = owner + editor
+	permission can_publish = (owner + editor & approver)
+	permission can_read = owner
+	permission can_view = owner + editor + reviewer
+	permission editor = t_editor
+	relation t_editor: learning/user
+	permission owner = t_owner
+	relation t_owner: learning/user
+	permission reviewer = t_reviewer
+	relation t_reviewer: learning/user
+}
+
+definition learning/project {
+	permission contributor = t_contributor
+	relation t_contributor: learning/user
+	permission owner = t_owner
+	relation t_owner: learning/user
+	permission secret_info = t_secret_info
+	relation t_secret_info: learning/user
+	permission team_member = t_team_member
+	relation t_team_member: learning/user
+}
+
+definition learning/user {}

tutorials/02_advanced_and_cross_namespace.zed

@@ -0,0 +1,41 @@
+definition files/document {
+	permission author = t_author
+	relation t_author: organization/user
+	permission can_read = author + t_folder->can_read
+	permission can_write = author + t_folder->can_manage
+	permission folder = t_folder
+	relation t_folder: files/folder
+	permission shared_with = t_shared_with
+	relation t_shared_with: organization/team#member
+}
+
+definition files/folder {
+	permission can_manage = owner + t_project->can_manage
+	permission can_read = owner + t_project->team_members + t_parent->can_read
+	permission owner = t_owner
+	relation t_owner: organization/user
+	permission parent = t_parent
+	relation t_parent: files/folder
+	permission project = t_project
+	relation t_project: organization/project
+}
+
+definition organization/project {
+	permission can_manage = t_owner_team->can_manage + t_owner_team->member
+	permission collaborator_teams = t_collaborator_teams
+	relation t_collaborator_teams: organization/team
+	permission managers = t_owner_team->manager
+	permission owner_team = t_owner_team
+	relation t_owner_team: organization/team
+	permission team_members = t_owner_team->member + t_collaborator_teams->member
+}
+
+definition organization/team {
+	permission can_manage = manager
+	permission manager = t_manager
+	relation t_manager: organization/user
+	permission member = t_member
+	relation t_member: organization/user
+}
+
+definition organization/user {}

tutorials/02_advanced_relations.ksl

@@ -0,0 +1,28 @@
+version 0.1
+namespace organization
+
+public type user {
+
+}
+
+public type team {
+    relation member: [Any user]
+    relation manager: [ExactlyOne user]
+
+    // Permission derived from relations
+    relation can_manage: manager
+}
+
+public type project {
+    relation owner_team: [ExactlyOne team]
+    relation collaborator_teams: [Any team]
+
+    // Nested relation access - access team's members through the relation
+    relation team_members: owner_team.member or collaborator_teams.member
+
+    // Nested relation with specific sub-relation
+    relation managers: owner_team.manager
+
+    // Complex nested permissions
+    relation can_manage: owner_team.can_manage or owner_team.member
+}

tutorials/02_cross_namespace.ksl

@@ -0,0 +1,28 @@
+version 0.1
+namespace files
+import organization
+
+public type folder {
+    // Cross-namespace type reference
+    relation owner: [ExactlyOne organization.user]
+    relation parent: [AtMostOne folder]
+    relation project: [AtMostOne organization.project]
+
+    // Cross-namespace nested relations
+    relation can_read: owner or project.team_members or parent.can_read
+
+    // Complex cross-namespace permissions
+    relation can_manage: owner or project.can_manage
+}
+
+public type document {
+    relation folder: [ExactlyOne folder]
+    relation author: [ExactlyOne organization.user]
+
+    // Inherit permissions from folder
+    relation can_read: author or folder.can_read
+    relation can_write: author or folder.can_manage
+
+    // Self-referencing with cross-namespace
+    relation shared_with: [Any organization.team.member]
+}

tutorials/03_complete_extensions.zed

@@ -0,0 +1,50 @@
+definition inventory/server {
+	permission can_delete = t_workspace->servers_delete
+	permission can_read = t_workspace->servers_read
+	permission can_write = t_workspace->servers_write
+	permission workspace = t_workspace
+	relation t_workspace: rbac/workspace
+}
+
+definition rbac/principal {}
+
+definition rbac/role {
+	permission global_all_permissions = t_global_all_permissions
+	relation t_global_all_permissions: rbac/principal:*
+	permission mod_inventory_all_rel_can_delete = t_mod_inventory_all_rel_can_delete
+	relation t_mod_inventory_all_rel_can_delete: rbac/principal:*
+	permission mod_inventory_all_rel_can_read = t_mod_inventory_all_rel_can_read
+	relation t_mod_inventory_all_rel_can_read: rbac/principal:*
+	permission mod_inventory_all_rel_can_write = t_mod_inventory_all_rel_can_write
+	relation t_mod_inventory_all_rel_can_write: rbac/principal:*
+	permission mod_inventory_type_server_all = t_mod_inventory_type_server_all
+	relation t_mod_inventory_type_server_all: rbac/principal:*
+	permission servers_delete = t_servers_delete
+	relation t_servers_delete: rbac/principal:*
+	permission servers_read = t_servers_read
+	relation t_servers_read: rbac/principal:*
+	permission servers_write = t_servers_write
+	relation t_servers_write: rbac/principal:*
+}
+
+definition rbac/role_binding {
+	permission granted = t_granted
+	relation t_granted: rbac/role
+	permission servers_delete = (subject & t_granted->servers_delete + t_granted->global_all_permissions + t_granted->mod_inventory_type_server_all + t_granted->mod_inventory_all_rel_can_delete)
+	permission servers_read = (subject & t_granted->servers_read + t_granted->global_all_permissions + t_granted->mod_inventory_type_server_all + t_granted->mod_inventory_all_rel_can_read)
+	permission servers_write = (subject & t_granted->servers_write + t_granted->global_all_permissions + t_granted->mod_inventory_type_server_all + t_granted->mod_inventory_all_rel_can_write)
+	permission subject = t_subject
+	relation t_subject: rbac/user
+}
+
+definition rbac/user {}
+
+definition rbac/workspace {
+	permission parent = t_parent
+	relation t_parent: rbac/workspace
+	permission servers_delete = t_user_grant->servers_delete + t_parent->servers_delete
+	permission servers_read = t_user_grant->servers_read + t_parent->servers_read
+	permission servers_write = t_user_grant->servers_write + t_parent->servers_write
+	permission user_grant = t_user_grant
+	relation t_user_grant: rbac/role_binding
+}

tutorials/03_extension_usage.ksl

@@ -0,0 +1,17 @@
+version 0.1
+namespace inventory
+import rbac
+
+public type server {
+    private relation workspace: [ExactlyOne rbac.workspace]
+
+    // Using the extension with @ syntax
+    @rbac.workspace_permission(permission_name:'servers_read')
+    public relation can_read: workspace.servers_read
+
+    @rbac.workspace_permission(permission_name:'servers_write')
+    public relation can_write: workspace.servers_write
+
+    @rbac.workspace_permission(permission_name:'servers_delete')
+    public relation can_delete: workspace.servers_delete
+}

tutorials/04_complete_real_world.ksl

@@ -0,0 +1,56 @@
+version 0.1
+namespace enterprise
+import rbac
+
+// Complete real-world example using EVERY KSL feature
+public type application {
+    // Cross-namespace import
+    private relation workspace: [ExactlyOne rbac.workspace]
+
+    // All cardinality types
+    relation owner: [ExactlyOne rbac.user]          // ExactlyOne
+    relation developers: [Any rbac.user]            // Any
+    relation tech_lead: [AtMostOne rbac.user]       // AtMostOne
+    relation stakeholders: [AtLeastOne rbac.user]   // AtLeastOne
+
+    // All visibility types
+    public relation can_deploy: owner or tech_lead
+    internal relation can_debug: developers or tech_lead
+    private relation admin_access: owner
+
+    // Complex relation expressions
+    relation can_read: owner or developers or stakeholders
+    relation can_write: (owner or tech_lead) and developers
+    relation can_manage: owner unless tech_lead
+    relation emergency_access: (owner or tech_lead) and stakeholders
+
+    // Cross-namespace nested relations
+    relation workspace_access: workspace.user_grant
+
+    // Extensions usage
+    @rbac.workspace_permission(permission_name:'app_deploy')
+    public relation deploy_permission: workspace.app_deploy
+
+    @rbac.workspace_permission(permission_name:'app_monitor')
+    public relation monitor_permission: workspace.app_monitor
+}
+
+// Demonstrating complex hierarchies
+public type environment {
+    relation application: [ExactlyOne application]
+    relation environment_manager: [ExactlyOne rbac.user]
+
+    // Inherit from application with additional restrictions
+    relation can_deploy: environment_manager and application.can_deploy
+    relation can_read: environment_manager or application.can_read
+
+    // Self-referencing hierarchy
+    relation parent_env: [AtMostOne environment]
+    relation inherited_access: parent_env.can_read or parent_env.can_deploy
+}
+
+// Using reserved keyword with escape
+public type database {
+    relation #version: [ExactlyOne rbac.user]  // Using # to escape reserved word
+    relation backup_access: [Any rbac.user]
+}

tutorials/04_complete_real_world.zed

@@ -0,0 +1,78 @@
+definition enterprise/application {
+	permission admin_access = owner
+	permission can_debug = developers + tech_lead
+	permission can_deploy = owner + tech_lead
+	permission can_manage = (owner - tech_lead)
+	permission can_read = owner + developers + stakeholders
+	permission can_write = (owner + tech_lead & developers)
+	permission deploy_permission = t_workspace->app_deploy
+	permission developers = t_developers
+	relation t_developers: rbac/user
+	permission emergency_access = (owner + tech_lead & stakeholders)
+	permission monitor_permission = t_workspace->app_monitor
+	permission owner = t_owner
+	relation t_owner: rbac/user
+	permission stakeholders = t_stakeholders
+	relation t_stakeholders: rbac/user
+	permission tech_lead = t_tech_lead
+	relation t_tech_lead: rbac/user
+	permission workspace = t_workspace
+	relation t_workspace: rbac/workspace
+	permission workspace_access = t_workspace->user_grant
+}
+
+definition enterprise/database {
+	permission backup_access = t_backup_access
+	relation t_backup_access: rbac/user
+	permission version = t_version
+	relation t_version: rbac/user
+}
+
+definition enterprise/environment {
+	permission application = t_application
+	relation t_application: enterprise/application
+	permission can_deploy = (environment_manager & t_application->can_deploy)
+	permission can_read = environment_manager + t_application->can_read
+	permission environment_manager = t_environment_manager
+	relation t_environment_manager: rbac/user
+	permission inherited_access = t_parent_env->can_read + t_parent_env->can_deploy
+	permission parent_env = t_parent_env
+	relation t_parent_env: enterprise/environment
+}
+
+definition rbac/principal {}
+
+definition rbac/role {
+	permission app_deploy = t_app_deploy
+	relation t_app_deploy: rbac/principal:*
+	permission app_monitor = t_app_monitor
+	relation t_app_monitor: rbac/principal:*
+	permission global_all_permissions = t_global_all_permissions
+	relation t_global_all_permissions: rbac/principal:*
+	permission mod_enterprise_all_rel_deploy_permission = t_mod_enterprise_all_rel_deploy_permission
+	relation t_mod_enterprise_all_rel_deploy_permission: rbac/principal:*
+	permission mod_enterprise_all_rel_monitor_permission = t_mod_enterprise_all_rel_monitor_permission
+	relation t_mod_enterprise_all_rel_monitor_permission: rbac/principal:*
+	permission mod_enterprise_type_application_all = t_mod_enterprise_type_application_all
+	relation t_mod_enterprise_type_application_all: rbac/principal:*
+}
+
+definition rbac/role_binding {
+	permission app_deploy = (subject & t_granted->app_deploy + t_granted->global_all_permissions + t_granted->mod_enterprise_type_application_all + t_granted->mod_enterprise_all_rel_deploy_permission)
+	permission app_monitor = (subject & t_granted->app_monitor + t_granted->global_all_permissions + t_granted->mod_enterprise_type_application_all + t_granted->mod_enterprise_all_rel_monitor_permission)
+	permission granted = t_granted
+	relation t_granted: rbac/role
+	permission subject = t_subject
+	relation t_subject: rbac/user
+}
+
+definition rbac/user {}
+
+definition rbac/workspace {
+	permission app_deploy = t_user_grant->app_deploy + t_parent->app_deploy
+	permission app_monitor = t_user_grant->app_monitor + t_parent->app_monitor
+	permission parent = t_parent
+	relation t_parent: rbac/workspace
+	permission user_grant = t_user_grant
+	relation t_user_grant: rbac/role_binding
+}