plutonium 0.15.5 → 0.15.7

data/app/views/layouts/rodauth.html.erb

@@ -12,8 +12,8 @@
         <%= yield %>
       </div>
   </div>
-  <div class="mt-4 flex items-center font-medium text-blue-600 dark:text-blue-500 hover:underline">
+  <div class="mt-4 flex items-center font-medium text-secondary-600 dark:text-secondary-400 hover:underline">
     <%= render_icon "outline/home" %>
-    <%= link_to "Home", root_path, class: "font-medium text-blue-600 dark:text-blue-500" %>
+    <%= link_to "Home", root_path, class: "font-medium text-secondary-600 dark:text-secondary-400" %>
   </div>
 <% end %>

data/docs/.vitepress/config.ts

@@ -0,0 +1,61 @@
+import { defineConfig } from "vitepress"
+import { withMermaid } from "vitepress-plugin-mermaid";
+
+const base = "/plutonium-core/"
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig(withMermaid({
+  base: base,
+  title: "Plutonium",
+  description: "The Ultimate Rapid Application Development Toolkit (RADKit) for Rails",
+  head: [["link", { rel: "icon", href: `${base}favicon.ico` }]],
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    logo: "/plutonium.png",
+    search: {
+      provider: 'local'
+    },
+    nav: [
+      { text: "Home", link: "/" },
+      { text: "Guide", link: "/guide/getting-started" }
+    ],
+    sidebar: {
+      '/guide/': [
+
+        {
+          text: "Introduction",
+          items: [
+            { text: "What is Plutonium?", link: "/guide/what-is-plutonium" },
+          ]
+        },
+        {
+          text: "Getting Started",
+          items: [
+            { text: "Overview", link: "/guide/getting-started/" },
+            { text: "Installation", link: "/guide/getting-started/installation" },
+            { text: "Core Concepts", link: "/guide/getting-started/core-concepts" },
+            { text: "Resources", link: "/guide/getting-started/resources" },
+            { text: "Authorization", link: "/guide/getting-started/authorization" },
+          ]
+        },
+        // { text: "Quick Start", link: "/installation" },
+
+        // {
+        //   text: "Examples",
+        //   items: [
+        //     { text: "Markdown Examples", link: "/installation" },
+        //     { text: "Runtime API Examples", link: "/api-examples" }
+        //   ]
+        // }
+      ]
+    },
+    socialLinks: [
+      { icon: "github", link: "https://github.com/radioactive-labs/plutonium-core" }
+    ],
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright © 2024-present Stefan Froelich'
+    }
+  },
+  cleanUrls: true,
+}))

data/docs/.vitepress/theme/custom.css

@@ -0,0 +1,61 @@
+/*
+
+Primary Colors:
+
+Coral/Orange Red: #FF4D4D (for main CTAs and primary elements)
+Deep Turquoise: #00CED1 (for secondary elements)
+Deep Blue: #1E3D59 (for text and accents)
+
+Accent Colors:
+
+Soft Pink: #FF9EAA (for highlights)
+Light Blue: #B8E3E9 (for backgrounds)
+White: #FFFFFF (for contrast and readability)
+
+*/
+
+:root {
+  /* Primary Brand Colors - Inspired by the vibrant gradient */
+  --vp-c-brand-1: #FF4D4D;
+  /* Vibrant coral red */
+  --vp-c-brand-2: #FF6B4A;
+  /* Lighter coral */
+  --vp-c-brand-3: #FF8347;
+  /* Soft orange */
+  --vp-c-brand-soft: rgba(255, 77, 77, 0.14);
+
+  /* Accent Colors */
+  --vp-c-accent-1: #00CED1;
+  /* Turquoise */
+  --vp-c-accent-2: #1E90FF;
+  /* Bright blue */
+  --vp-c-accent-3: #4169E1;
+  /* Royal blue */
+  --vp-c-accent-soft: rgba(0, 206, 209, 0.14);
+
+  /* Custom Background Gradients */
+  --vp-home-hero-name-background: linear-gradient(120deg,
+      #FF4D4D 30%,
+      #00CED1);
+
+  /* Updating existing color references */
+  --vp-c-tip-1: var(--vp-c-accent-1);
+  --vp-c-tip-2: var(--vp-c-accent-2);
+  --vp-c-tip-3: var(--vp-c-accent-3);
+  --vp-c-tip-soft: var(--vp-c-accent-soft);
+}
+
+.dark {
+  /* Dark mode adjustments */
+  --vp-c-brand-1: #FF6B4A;
+  /* Slightly lighter coral for dark mode */
+  --vp-c-brand-2: #FF4D4D;
+  --vp-c-brand-3: #FF3333;
+  --vp-c-brand-soft: rgba(255, 107, 74, 0.16);
+
+  --vp-c-accent-1: #40E0E3;
+  /* Brighter turquoise for dark mode */
+  --vp-c-accent-2: #45A3FF;
+  --vp-c-accent-3: #6182E3;
+  --vp-c-accent-soft: rgba(64, 224, 227, 0.16);
+}

data/docs/.vitepress/theme/index.ts

@@ -0,0 +1,4 @@
+import DefaultTheme from "vitepress/theme"
+import "./custom.css"
+
+export default DefaultTheme

data/docs/api-examples.md

@@ -0,0 +1,49 @@
+---
+outline: deep
+---
+
+# Runtime API Examples
+
+This page demonstrates usage of some of the runtime APIs provided by VitePress.
+
+The main `useData()` API can be used to access site, theme, and page data for the current page. It works in both `.md` and `.vue` files:
+
+```md
+<script setup>
+import { useData } from 'vitepress'
+
+const { theme, page, frontmatter } = useData()
+</script>
+
+## Results
+
+### Theme Data
+<pre>{{ theme }}</pre>
+
+### Page Data
+<pre>{{ page }}</pre>
+
+### Page Frontmatter
+<pre>{{ frontmatter }}</pre>
+```
+
+<script setup>
+import { useData } from 'vitepress'
+
+const { site, theme, page, frontmatter } = useData()
+</script>
+
+## Results
+
+### Theme Data
+<pre>{{ theme }}</pre>
+
+### Page Data
+<pre>{{ page }}</pre>
+
+### Page Frontmatter
+<pre>{{ frontmatter }}</pre>
+
+## More
+
+Check out the documentation for the [full list of runtime APIs](https://vitepress.dev/reference/runtime-api#usedata).

data/docs/guide/getting-started/authorization.md

@@ -0,0 +1,296 @@
+# Authorization and Access Control
+
+Plutonium provides a robust authorization system built on top of [Action Policy](https://actionpolicy.evilmartians.io/), offering fine-grained access control, resource scoping, and entity-based authorization.
+
+## Overview
+
+Authorization in Plutonium operates at multiple levels:
+- Resource-level policies
+- Action-based permissions
+- Entity-based scoping
+- Attribute-level access control
+
+## Basic Policy Definition
+
+Every resource in Plutonium requires a policy. Here's a basic example:
+
+```ruby
+class BlogPolicy < ResourcePolicy
+  # Core CRUD Permissions
+
+  def create?
+    # All authenticated users can create blogs
+    true
+  end
+
+  def read?
+    # Allow anyone to read blogs
+    true
+  end
+
+  def update?
+    # Allow only the blog owner to update
+    owner?
+  end
+
+  def destroy?
+    # Allow only the blog owner or admins to destroy
+    owner? || user.admin?
+  end
+
+  # Attribute Control
+
+  def permitted_attributes_for_create
+    [:title, :content, :category]
+  end
+
+  def permitted_attributes_for_read
+    [:title, :content, :category, :created_at, :updated_at, :user_id]
+  end
+
+  def permitted_attributes_for_update
+    [:title, :content, :category]
+  end
+
+  # Association Access
+
+  def permitted_associations
+    [:comments]
+  end
+
+  private
+
+  def owner?
+    record.user_id == user.id
+  end
+end
+```
+
+## Default Behaviors in Plutonium Policies
+
+::: info Overview
+Plutonium's Policy system implements a secure-by-default pattern with clear inheritance chains for both permissions and attribute access.
+:::
+
+### Permission Defaults
+
+Permission methods follow two key patterns: core permissions that default to `false`, and derived permissions that inherit from core ones.
+
+#### Core Permission Chain
+
+```mermaid
+graph TD
+    subgraph Core Permissions
+        A[create? ❌] --> B[update? ❌]
+        A --> C[destroy? ❌]
+        D[read? ❌] --> E[index? ❌]
+        D --> F[show? ❌]
+    end
+```
+
+::: warning Security First
+All core permissions (`create?` and `read?`) default to `false`. You must explicitly override these to grant access.
+```ruby
+# Default implementations
+def create?
+  false
+end
+
+def read?
+  false
+end
+```
+:::
+
+#### Permission Inheritance
+
+::: code-group
+```ruby [Action Methods]
+def update?
+  create?    # Inherits from create?
+end
+
+def destroy?
+  create?    # Inherits from create?
+end
+
+def index?
+  read?      # Inherits from read?
+end
+
+def show?
+  read?      # Inherits from read?
+end
+```
+
+```ruby [Helper Methods]
+def new?
+  create?    # Matches create?
+end
+
+def edit?
+  update?    # Matches update?
+end
+
+def search?
+  index?     # Matches index?
+end
+```
+:::
+
+### Attribute Permission Defaults
+
+Attribute permissions also follow an inheritance pattern, but with auto-detection in development:
+
+::: details Inheritance Chain
+```mermaid
+graph TD
+    subgraph Core Attributes
+        A[permitted_attributes_for_create] --> B[permitted_attributes_for_update]
+        C[permitted_attributes_for_read] --> D[permitted_attributes_for_show]
+        C --> E[permitted_attributes_for_index]
+    end
+```
+:::
+
+#### Core Implementation Details
+
+::: code-group
+```ruby [Create Attributes]
+def permitted_attributes_for_create
+  # Auto-detects fields but excludes system columns
+  autodetect_permitted_fields(:permitted_attributes_for_create) - [
+    resource_class.primary_key.to_sym,
+    :created_at,
+    :updated_at
+  ]
+end
+```
+
+```ruby [Read Attributes]
+def permitted_attributes_for_read
+  # Auto-detects all fields
+  autodetect_permitted_fields(:permitted_attributes_for_read)
+end
+```
+
+```ruby [Update Attributes]
+def permitted_attributes_for_update
+  # Inherits from create
+  permitted_attributes_for_create
+end
+```
+:::
+
+::: danger Auto-detection Warning
+The default attribute detection:
+- Only works in development
+- Raises errors in other environments
+- Shows warning messages
+- Must be overridden in production
+:::
+
+### Association Defaults
+
+By default, no associations are permitted:
+
+```ruby
+def permitted_associations
+  []  # Must be explicitly defined
+end
+```
+
+### Context Object Defaults
+
+Two built-in authorization contexts:
+
+::: code-group
+```ruby [Required Context]
+# User must be present
+authorize :user, allow_nil: false
+```
+
+```ruby [Optional Context]
+# Entity scope is optional
+authorize :entity_scope, allow_nil: true
+```
+:::
+
+#### Default Scoping Behavior
+
+When an entity scope exists, records are automatically filtered:
+
+```ruby
+relation_scope do |relation|
+  next relation unless entity_scope
+  relation.associated_with(entity_scope)
+end
+```
+
+#### Adding Custom Contexts
+
+You can add additional authorization contexts:
+
+::: code-group
+```ruby [Policy]
+class BlogPolicy < ResourcePolicy
+  authorize :ability, allow_nil: true
+
+  def promote?
+    user.admin? && ability&.can?(:promote, record)
+  end
+end
+```
+
+```ruby [Controller]
+class BlogsController < ResourceController
+  authorize :ability, through: :current_ability
+
+  private
+
+  def current_ability
+    @current_ability ||= Ability.new(current_user)
+  end
+end
+```
+:::
+
+## Quick Reference
+
+| Method Type | Default | Inherits From |
+|------------|---------|---------------|
+| create? | false | - |
+| read? | false | - |
+| update? | false | create? |
+| destroy? | false | create? |
+| index? | false | read? |
+| show? | false | read? |
+| attributes_for_create | auto* | - |
+| attributes_for_read | auto* | - |
+| attributes_for_update | auto* | create |
+| associations | [] | - |
+
+::: warning
+\*Auto-detection only works in development
+:::
+
+## Security Best Practices
+
+### 1. Never Skip Authorization
+
+Plutonium controllers automatically verify authorization:
+
+```ruby
+class BlogsController < ResourceController
+  def show
+    # This will raise an error if you forget to authorize
+    # authorize! resource_record
+    render :show
+  end
+end
+```
+
+## Related Resources
+
+- [Action Policy Documentation](https://actionpolicy.evilmartians.io/)
+- [Rails Security Guide](https://guides.rubyonrails.org/security.html)