@plutocms/pluto 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Changelog
 
 
+## [0.5.0](https://github.com/plutocms/pluto/compare/v0.4.0...v0.5.0) (2026-09-12)
+
+
+### Features
+
+* **permissions:** add capability registry and usePlutoPermissions composable ([#129](https://github.com/plutocms/pluto/issues/129)) ([c98419f](https://github.com/plutocms/pluto/commit/c98419fc967f8e20678389169e937db759c308bc))
+
 ## [0.4.0](https://github.com/plutocms/pluto/compare/v0.3.2...v0.4.0) (2026-09-12)
 
 

package/FEATURES.md

@@ -9,3 +9,6 @@ policies shared by every project here.
 - Extension registry: a typed, ordered, reactive registry that lets a layer plug its admin-UI
   pieces (navbar, sidebar nav, pages, dashboard widgets, settings panels and driver) into core
   with one function call. @.claude/skills/extension-registry/SKILL.md
+- Permissions: a typed capability registry and a `usePlutoPermissions()` composable that let a
+  layer declare capabilities and check what the current user holds, backed by a registered
+  permissions driver. @.claude/skills/permissions/SKILL.md

package/app/composables/pluto-extension.ts

@@ -21,4 +21,9 @@ export function definePlutoExtension(definition: PlutoExtension): void {
     definition.settingsDriver ? [definition.settingsDriver] : []
   )
   registry.dashboardWidgets.set(definition.id, definition.dashboardWidgets ?? [])
+  registry.capabilities.set(definition.id, definition.capabilities ?? [])
+  registry.permissionsDrivers.set(
+    definition.id,
+    definition.permissionsDriver ? [definition.permissionsDriver] : []
+  )
 }

package/app/composables/pluto-permissions.ts

@@ -0,0 +1,74 @@
+/** Capabilities declared by every layer, in registry order. */
+export function usePlutoCapabilities() {
+  const registry = usePlutoRegistry()
+  return { items: registry.capabilities.list }
+}
+
+/**
+ * The current user's capabilities, backed by whichever permissions driver
+ * is registered. `useState` is correct for the loaded list itself (plain
+ * strings, and /admin/** is client-only per nuxt.config.ts) — this
+ * mirrors usePlutoSettings()'s values/dirty state exactly. The driver
+ * registration itself goes through the registry, same as
+ * PlutoSettingsDriver.
+ */
+export function usePlutoPermissions() {
+  const registry = usePlutoRegistry()
+  const driver = computed(() => registry.permissionsDrivers.list.value.at(-1) ?? null)
+
+  const granted = useState<string[]>('pluto-permissions-granted', () => [])
+  const loaded = useState<boolean>('pluto-permissions-loaded', () => false)
+  const status = ref<'idle' | 'loading'>('idle')
+
+  async function load() {
+    if (!driver.value) {
+      return
+    }
+
+    status.value = 'loading'
+    try {
+      granted.value = await driver.value.load()
+      loaded.value = true
+    } finally {
+      status.value = 'idle'
+    }
+  }
+
+  function clear() {
+    granted.value = []
+    loaded.value = false
+  }
+
+  /**
+   * True when the user holds this capability.
+   *
+   * Fails OPEN when no permissions driver is registered — a site with no
+   * permissions backend also has no server-side guard, so hiding UI in
+   * that case would only be theatre, and would break a core-only
+   * install with nothing registered yet. Read `hasDriver` to tell the two
+   * cases apart if a caller needs to.
+   *
+   * This is never a security boundary by itself. The server-side guard
+   * (a backend layer's own requireCapability-equivalent, backed by RLS)
+   * is what actually enforces anything. This only decides what the UI
+   * shows.
+   */
+  function can(capability: string): boolean {
+    if (!driver.value) {
+      return true
+    }
+
+    return granted.value.includes('*') || granted.value.includes(capability)
+  }
+
+  return {
+    granted,
+    loaded,
+    status,
+    hasDriver: computed(() => Boolean(driver.value)),
+    isAdmin: computed(() => granted.value.includes('*')),
+    load,
+    clear,
+    can,
+  }
+}

package/app/composables/pluto-registry.ts

@@ -21,6 +21,8 @@ export function usePlutoRegistry(): PlutoRegistry {
       settingsPanels: createOwnedRegistry<PlutoSettingsPanel>(),
       settingsDrivers: createOwnedRegistry<PlutoSettingsDriver>(),
       dashboardWidgets: createOwnedRegistry<PlutoDashboardWidget>(),
+      capabilities: createOwnedRegistry<PlutoCapability>(),
+      permissionsDrivers: createOwnedRegistry<PlutoPermissionsDriver>(),
     }
   }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plutocms/pluto",
   "type": "module",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The layerable CMS",
   "author": "Victor Ribeiro",
   "license": "MIT",

package/shared/types/registry.ts

@@ -59,6 +59,32 @@ export interface PlutoSettingsDriver extends PlutoEntry {
   save: (patch: Record<string, string>) => Promise<void>
 }
 
+/**
+ * A capability a layer defines. `key` is the real capability string, for
+ * example 'posts:publish'. It is kept separate from `id` on purpose: the
+ * registry rewrites `id` to '<extensionId>:<id>' (see registry-factory.ts),
+ * which would corrupt a capability string if `id` were reused as the
+ * capability itself. `id` identifies this registry entry; `key` identifies
+ * the permission.
+ */
+export interface PlutoCapability extends PlutoEntry {
+  /** Format: '<namespace>:<action>', lowercase, for example 'posts:publish'. */
+  key: string
+  label: string
+  description?: string
+}
+
+/**
+ * Loads the current user's capability list. One backend layer registers
+ * this, the same way one layer registers a PlutoSettingsDriver. `load`
+ * returns a flat list of capability key strings the user holds. The
+ * single entry '*' means "every capability" (used by the built-in admin
+ * role).
+ */
+export interface PlutoPermissionsDriver extends PlutoEntry {
+  load: () => Promise<string[]>
+}
+
 export interface PlutoExtension {
   /** Layer name. Use the package's $meta.name, e.g. 'supabase-blog'. */
   id: string
@@ -69,6 +95,8 @@ export interface PlutoExtension {
   dashboardWidgets?: PlutoDashboardWidget[]
   settingsPanels?: PlutoSettingsPanel[]
   settingsDriver?: PlutoSettingsDriver
+  capabilities?: PlutoCapability[]
+  permissionsDriver?: PlutoPermissionsDriver
 }
 
 /**
@@ -91,4 +119,6 @@ export interface PlutoRegistry {
   settingsPanels: PlutoRegistryBucket<PlutoSettingsPanel>
   settingsDrivers: PlutoRegistryBucket<PlutoSettingsDriver>
   dashboardWidgets: PlutoRegistryBucket<PlutoDashboardWidget>
+  capabilities: PlutoRegistryBucket<PlutoCapability>
+  permissionsDrivers: PlutoRegistryBucket<PlutoPermissionsDriver>
 }