@bananapus/ownable-v6 0.0.19 → 0.0.21

package/ADMINISTRATION.md

@@ -11,14 +11,14 @@
 
 ## Purpose
 
-`nana-ownable-v6` does not introduce a new admin surface by itself. It defines how ownership is resolved for other repos. The important control question is how a contract's `owner()` is determined and how delegated permission IDs behave across ownership transfers.
+`nana-ownable-v6` does not add a new admin surface by itself. It defines how ownership is resolved for other repos. The important question is how a contract's `owner()` is determined and how delegated permission IDs behave across ownership transfers.
 
 ## Control Model
 
-- Ownership can be address-based or project-based.
-- Delegated operator checks run through `JBPermissions`.
-- Transfer and renounce semantics are part of the primitive.
-- Permission delegation resets on ownership transfer.
+- ownership can be address-based or project-based
+- delegated operator checks run through `JBPermissions`
+- transfer and renounce semantics are part of the primitive
+- delegated permission resets on ownership transfer
 
 ## Roles
 
@@ -40,34 +40,34 @@ The meaningful control surfaces are inherited by downstream contracts:
 
 ## Immutable And One-Way
 
-- Project ownership changes dynamically with project NFT transfers.
-- Delegated permission ID resets on ownership transfer.
-- Renouncing ownership is final unless the inheriting contract adds a separate recovery path.
+- project ownership changes dynamically with project NFT transfers
+- delegated permission ID resets on ownership transfer
+- renouncing ownership is final unless the inheriting contract adds a separate recovery path
 
 ## Operational Notes
 
-- Treat project-based ownership as live routing, not a snapshot.
-- Do not assume an operator permission survives ownership transfer.
-- Treat `setPermissionId(...)` as a real authority change because it rewires which delegated permission bit counts as owner access.
-- Review the inheriting contract, not just this primitive, to understand the full admin surface.
+- treat project-based ownership as live routing, not a snapshot
+- do not assume an operator permission survives ownership transfer
+- treat `setPermissionId(...)` as a real authority change because it rewires which delegated permission bit counts as owner access
+- review the inheriting contract, not just this primitive, to understand the full admin surface
 
 ## Machine Notes
 
-- Do not conclude authority from this repo alone; follow the inheriting contract's `onlyOwner` surfaces.
-- Treat ownership transfer as potentially changing both the owner identity and the usable delegated permission ID.
-- If the current permission ID is undocumented, inspect `jbOwner.permissionId` before reasoning about delegated owner access.
-- If a downstream repo uses project-based ownership, re-evaluate owner resolution after every project NFT transfer.
+- do not conclude authority from this repo alone; follow the inheriting contract's `onlyOwner` surfaces
+- treat ownership transfer as potentially changing both the owner identity and the usable delegated permission ID
+- if the current permission ID is undocumented, inspect `jbOwner.permissionId` before reasoning about delegated owner access
+- if a downstream repo uses project-based ownership, re-evaluate owner resolution after every project NFT transfer
 
 ## Recovery
 
-- This primitive has no protocol-wide recovery surface.
-- If ownership was transferred to the wrong project or address, recovery depends on the inheriting contract still recognizing the current owner.
+- this primitive has no protocol-wide recovery surface
+- if ownership was transferred to the wrong project or address, recovery depends on the inheriting contract still recognizing the current owner
 
 ## Admin Boundaries
 
-- This repo does not create a new permission namespace.
-- It cannot make an inheriting contract safer than that contract's own privileged functions.
-- It cannot preserve delegated operators across ownership transfer by default.
+- this repo does not create a new permission namespace
+- it cannot make an inheriting contract safer than that contract's own privileged functions
+- it cannot preserve delegated operators across ownership transfer by default
 
 ## Source Map
 

package/ARCHITECTURE.md

@@ -6,15 +6,17 @@
 
 ## System Overview
 
-The repo is an ownership primitive, not a policy layer. `JBOwnable` exposes a familiar inheritance surface. `JBOwnableOverrides` implements dynamic owner resolution, ownership transfer, renounce behavior, and delegated permission checks. Ownership can follow the current holder of a Juicebox project NFT instead of being fixed to an address.
+This repo is an ownership primitive, not a policy layer. `JBOwnable` gives downstream repos a familiar inheritance surface. `JBOwnableOverrides` implements dynamic owner resolution, ownership transfer, renounce behavior, and delegated permission checks.
+
+Ownership can follow the current holder of a Juicebox project NFT instead of staying fixed to one address.
 
 ## Core Invariants
 
-- Project-owned contracts must resolve the owner dynamically from the current project NFT holder.
-- The delegated permission ID resets on ownership transfer.
-- Pointing ownership at an unminted project can temporarily lock the contract until that project exists.
-- A burned or otherwise unresolvable project NFT effectively renounces ownership.
-- This repo should stay a drop-in primitive, not grow product-specific access rules.
+- project-owned contracts must resolve the owner dynamically from the current project NFT holder
+- the delegated permission ID resets on ownership transfer
+- pointing ownership at an unminted project can temporarily lock the contract until that project exists
+- an invalid or otherwise unresolvable project NFT effectively renounces ownership
+- this repo should stay a drop-in primitive, not grow product-specific access rules
 
 ## Modules
 
@@ -27,9 +29,9 @@ The repo is an ownership primitive, not a policy layer. `JBOwnable` exposes a fa
 
 ## Trust Boundaries
 
-- Ownership resolution depends on `JBProjects` and `JBPermissions` from `nana-core-v6`.
-- This repo does not create a new permission namespace.
-- Contracts that inherit from it may still add policy on top, but the resolution semantics here are infrastructure-level.
+- ownership resolution depends on `JBProjects` and `JBPermissions` from `nana-core-v6`
+- this repo does not create a new permission namespace
+- inheriting contracts may add policy on top, but the resolution semantics here are infrastructure-level
 
 ## Critical Flows
 
@@ -45,20 +47,20 @@ onlyOwner modifier
 
 ## Accounting Model
 
-No treasury accounting lives here. The critical state is ownership resolution data and delegated permission ID.
+No treasury accounting lives here. The important state is ownership resolution data and delegated permission ID.
 
 ## Security Model
 
-- Ownership resolution edge cases are more important than surface API shape.
-- Permission delegation is simple conceptually but security-sensitive because it composes with a global permission registry.
-- Unresolvable project ownership is intentionally fail-closed. If `PROJECTS.ownerOf()` cannot resolve, `onlyOwner` should stop working rather than inventing fallback authority.
+- ownership resolution edge cases matter more than surface API shape
+- permission delegation is simple but security-sensitive because it composes with a global permission registry
+- unresolvable project ownership is intentionally fail-closed
 
 ## Safe Change Guide
 
-- Be conservative with transfer and renounce semantics.
-- If event emission or transfer behavior changes, inspect deployer wrappers and inheriting repos.
-- If project-based ownership semantics change, re-check unminted-project and unresolvable-project behavior explicitly.
-- Do not make delegated permission IDs sticky across ownership transfers.
+- be conservative with transfer and renounce semantics
+- if event emission or transfer behavior changes, inspect deployer wrappers and inheriting repos
+- if project-based ownership semantics change, re-check unminted-project and unresolvable-project behavior explicitly
+- do not make delegated permission IDs sticky across ownership transfers
 
 ## Canonical Checks
 

package/AUDIT_INSTRUCTIONS.md

@@ -1,10 +1,11 @@
 # Audit Instructions
 
-This repo provides ownership helpers that can follow Juicebox project NFTs instead of a fixed EOA. It is a small repo with disproportionate privilege impact.
+This repo provides ownership helpers that can follow Juicebox project NFTs instead of a fixed EOA. It is a small repo with outsized privilege impact.
 
 ## Audit Objective
 
 Find issues that:
+
 - let unauthorized actors satisfy owner checks
 - break ownership updates when a project NFT moves, burns, or locks
 - let override logic produce a different owner than the project system intends
@@ -13,6 +14,7 @@ Find issues that:
 ## Scope
 
 In scope:
+
 - `src/JBOwnable.sol`
 - `src/JBOwnableOverrides.sol`
 - `src/interfaces/`
@@ -25,7 +27,8 @@ In scope:
 
 ## Security Model
 
-These contracts abstract “owner” as a project-based identity. Downstream repos use them to:
+These contracts abstract "owner" as a project-based identity. Downstream repos use them to:
+
 - treat a Juicebox project owner as contract owner
 - apply per-project override rules
 - keep admin power aligned with project NFT ownership instead of a static address
@@ -45,14 +48,12 @@ These contracts abstract “owner” as a project-based identity. Downstream rep
 
 ## Critical Invariants
 
-1. Owner resolution is correct
-For any supported mode, `owner()` or equivalent checks must resolve to the intended authority and no one else.
-
-2. Burn and lock behavior is safe
-If project ownership is intentionally burned or locked, the helper must not accidentally reopen control or brick valid admin paths.
-
-3. Override precedence is coherent
-Overrides must not silently supersede project ownership in cases the design does not permit.
+1. Owner resolution is correct.  
+   For any supported mode, `owner()` and owner checks must resolve to the intended authority and no one else.
+2. Burn and lock behavior is safe.  
+   If project ownership is intentionally burned or locked, the helper must not accidentally reopen control or brick valid admin paths.
+3. Override precedence is coherent.  
+   Overrides must not silently supersede project ownership in cases the design does not permit.
 
 ## Attack Surfaces
 

package/README.md

@@ -1,6 +1,6 @@
 # Juicebox Ownable
 
-`@bananapus/ownable-v6` is an ownership helper for contracts that should be controlled by a Juicebox project rather than a fixed wallet. It keeps the familiar `Ownable` shape while letting ownership follow a project NFT and optional delegated permissions.
+`@bananapus/ownable-v6` is an ownership helper for contracts that should be controlled by a Juicebox project instead of a fixed wallet. It keeps the familiar `Ownable` shape while letting ownership follow a project NFT and optional delegated permissions.
 
 Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)  
 User journeys: [USER_JOURNEYS.md](./USER_JOURNEYS.md)  
@@ -11,32 +11,32 @@ Audit instructions: [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md)
 
 ## Overview
 
-This package extends the standard ownership model in three useful ways:
+This package extends the standard ownership model in three ways:
 
 - ownership can point to a Juicebox project ID instead of an address
-- `owner()` resolves dynamically to the current holder of that project NFT when the referenced project remains readable
-- delegated operators can satisfy `onlyOwner` through a configurable `JBPermissions` permission ID
+- `owner()` can resolve dynamically to the current holder of that project NFT
+- delegated operators can satisfy `onlyOwner` through a configured `JBPermissions` permission ID
 
-For contracts that are already conceptually "owned by the project," this avoids manual ownership transfers when the project NFT changes hands.
+For contracts that are already meant to be owned by a project, this avoids manual ownership transfers when the project NFT changes hands.
 
-Use this repo when ownership should follow a Juicebox project. Do not use it if plain single-address ownership is good enough; standard `Ownable` is simpler.
+Use this repo when ownership should follow a Juicebox project. Do not use it if plain single-address ownership is enough. Standard `Ownable` is simpler.
 
-If your issue is in project ownership itself, start in `nana-core-v6` and `JBProjects`. This repo starts mattering when another contract wants its own admin surface to follow that project ownership.
+If the issue is in project ownership itself, start in `nana-core-v6` and `JBProjects`. This repo matters when another contract wants its admin surface to follow that project ownership.
 
 ## Key Contracts
 
 | Contract | Role |
 | --- | --- |
-| `JBOwnable` | Concrete contract to inherit when you want Juicebox-aware ownership with the standard `onlyOwner` interface. |
-| `JBOwnableOverrides` | Abstract base that holds the owner-resolution and permission-checking logic. |
+| `JBOwnable` | Concrete contract to inherit when you want Juicebox-aware ownership with a standard `onlyOwner` interface. |
+| `JBOwnableOverrides` | Abstract base that holds owner resolution and delegated-permission logic. |
 | `IJBOwnable` | Interface for queries, transfers, permission ID changes, and events. |
 
 ## Mental Model
 
-This package is a thin ownership adapter:
+This package is a small ownership adapter:
 
 1. resolve who the effective owner is
-2. optionally delegate `onlyOwner` through a permission ID
+2. optionally allow a delegated permission to satisfy `onlyOwner`
 3. preserve an `Ownable`-like interface for downstream contracts
 
 ## Read These Files First
@@ -47,16 +47,16 @@ This package is a thin ownership adapter:
 
 ## Integration Traps
 
-- ownership may resolve to a project NFT holder rather than a fixed address, so caching `owner()` off-chain can become stale
-- `owner()` can resolve to `address(0)` if the referenced project NFT is burned, invalid, or otherwise unreadable, which effectively renounces the contract
+- ownership may resolve to a project NFT holder instead of a fixed address, so caching `owner()` off-chain can go stale
+- `owner()` can resolve to `address(0)` if the referenced project NFT is invalid or unreadable, which effectively renounces the contract
 - delegated operator access depends on a chosen permission ID, not on a generic admin role
 - ownership transfer and permission-ID updates are part of the security model, not just convenience helpers
 
 ## Where State Lives
 
-- effective ownership configuration lives in `JBOwnableOverrides`
-- downstream contract state still lives in the inheriting contract, not in this package
-- project ownership truth lives in `nana-core-v6` when the owner target is a Juicebox project
+- effective ownership configuration: `JBOwnableOverrides`
+- downstream contract state: the inheriting contract
+- project ownership truth: `nana-core-v6` when the owner target is a Juicebox project
 
 ## High-Signal Tests
 
@@ -94,9 +94,9 @@ test/
 ## Risks And Notes
 
 - if ownership is tied to a project NFT and that NFT becomes unreachable, the contract is effectively locked
-- delegated access depends on a chosen permission ID, so collisions with other permission schemes are an operational risk
-- permission IDs reset on ownership transfer, which is safer by default but easy to miss if an integration expects long-lived operator access
-- transferring ownership to a project validates that the project exists, but later project-NFT invalidation can still collapse effective ownership to `address(0)`
+- delegated access depends on a chosen permission ID, so bad permission selection is an operational risk
+- permission IDs reset on ownership transfer, which is safer by default but easy to miss
+- transferring ownership to a project validates that the project exists at transfer time, but later project invalidation can still collapse effective ownership to `address(0)`
 
 ## For AI Agents
 

package/SKILLS.md

@@ -2,8 +2,8 @@
 
 ## Use This File For
 
-- Use this file when the task involves project-based ownership, delegated `onlyOwner` permissions, or how ownership should follow a Juicebox project NFT instead of a fixed wallet.
-- Start here, then decide whether the question is about owner resolution, permission delegation, or ownership transfer semantics. Those surfaces are intentionally compact but security-sensitive.
+- Use this file when the task involves project-based ownership, delegated `onlyOwner` permissions, or ownership that should follow a Juicebox project NFT instead of a fixed wallet.
+- Start here, then decide whether the question is about owner resolution, permission delegation, or ownership transfer semantics.
 
 ## Read This Next
 
@@ -25,7 +25,7 @@
 
 ## Purpose
 
-Ownership adapter for contracts that should follow Juicebox project ownership instead of a fixed address, with optional delegated permission IDs layered on top of the familiar `Ownable` pattern.
+Ownership adapter for contracts that should follow Juicebox project ownership instead of a fixed address, with optional delegated permission IDs on top of the familiar `Ownable` pattern.
 
 ## Reference Files
 
@@ -36,6 +36,6 @@ Ownership adapter for contracts that should follow Juicebox project ownership in
 
 - Start in [`src/JBOwnableOverrides.sol`](./src/JBOwnableOverrides.sol) when the question is about who the effective owner is or why `onlyOwner` passed or failed.
 - Treat ownership transfer and delegated permission resets as security-sensitive.
-- Project-based ownership can intentionally become unusable if it points at an unminted or invalid project. Treat that as a deployment invariant, not a runtime surprise.
+- Project-based ownership can intentionally become unusable if it points at an unminted or invalid project.
 - Unminted or unexpectedly transferred project NFTs can change the effective owner surface. Check the project lifecycle, not just this adapter.
-- When a bug looks like project ownership itself, confirm whether the real source is upstream in `nana-core-v6` rather than this adapter layer.
+- When a bug looks like project ownership itself, confirm whether the real source is upstream in `nana-core-v6` rather than this adapter.

package/USER_JOURNEYS.md

@@ -2,9 +2,7 @@
 
 ## Repo Purpose
 
-This repo adapts `Ownable`-style control to Juicebox project ownership and project-scoped operator permissions.
-It is an ownership adapter. It does not replace the underlying ownership or permission registries in
-[nana-core-v6](../nana-core-v6/USER_JOURNEYS.md).
+This repo adapts `Ownable`-style control to Juicebox project ownership and project-scoped operator permissions. It is an ownership adapter. It does not replace the underlying ownership or permission registries in [nana-core-v6](../nana-core-v6/USER_JOURNEYS.md).
 
 ## Primary Actors
 
@@ -31,7 +29,7 @@ It is an ownership adapter. It does not replace the underlying ownership or perm
 **Main Flow**
 1. Inherit `JBOwnable` or `JBOwnableOverrides`.
 2. Initialize ownership with the relevant project ID and `JBProjects` reference.
-3. Let `owner()` resolve through the current project NFT holder rather than a fixed address.
+3. Let `owner()` resolve through the current project NFT holder instead of a fixed address.
 
 **Failure Modes**
 - the contract assumes ordinary `Ownable` transfer semantics after adopting project-based ownership
@@ -59,7 +57,7 @@ It is an ownership adapter. It does not replace the underlying ownership or perm
 **Failure Modes**
 - teams grant a broader permission than intended
 - downstream reviewers forget that `onlyOwner` may resolve through permissions instead of direct ownership
-- operators retain stale permissions after governance changes
+- operators keep stale permissions after governance changes
 
 **Postconditions**
 - the chosen operator can satisfy `onlyOwner` without receiving direct ownership of the project or contract
@@ -99,11 +97,11 @@ It is an ownership adapter. It does not replace the underlying ownership or perm
 **Main Flow**
 1. Use `transferOwnership(...)` for an address owner or `transferOwnershipToProject(...)` for a project owner.
 2. Re-establish delegated permission policy if the new owner still wants operators.
-3. Renounce or burn only when permanent admin loss is intentional.
+3. Renounce only when permanent admin loss is intentional.
 
 **Failure Modes**
 - ownership is burned even though the downstream contract still needs administration
-- teams forget that permission-ID delegation resets across ownership changes
+- teams forget that delegated permissions reset across ownership changes
 
 **Postconditions**
 - control moves to the chosen address or project, or is intentionally removed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/ownable-v6",
-  "version": "0.0.19",
+  "version": "0.0.21",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -10,8 +10,8 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@bananapus/core-v6": "^0.0.34",
-    "@bananapus/permission-ids-v6": "^0.0.17",
+    "@bananapus/core-v6": "^0.0.36",
+    "@bananapus/permission-ids-v6": "^0.0.19",
     "@openzeppelin/contracts": "^5.6.1"
   },
   "scripts": {

package/src/JBOwnableOverrides.sol

@@ -134,6 +134,17 @@ abstract contract JBOwnableOverrides is Context, JBPermissioned, IJBOwnable {
             }
         }
 
+        // When permissionId is 0 (direct-owner-only mode), bypass the permission system entirely.
+        // This ensures ROOT operators cannot act as owner when delegation is disabled.
+        if (ownerInfo.permissionId == 0) {
+            if (_msgSender() != resolvedOwner) {
+                revert JBPermissioned.JBPermissioned_Unauthorized({
+                    account: resolvedOwner, sender: _msgSender(), projectId: ownerInfo.projectId, permissionId: 0
+                });
+            }
+            return;
+        }
+
         _requirePermissionFrom({
             account: resolvedOwner, projectId: ownerInfo.projectId, permissionId: ownerInfo.permissionId
         });

package/test/regression/RootPermissionBypassesPermissionIdZero.t.sol

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity 0.8.28;
+
+import {Test} from "forge-std/Test.sol";
+
+import {MockOwnable} from "../mocks/MockOwnable.sol";
+
+import {JBPermissioned} from "@bananapus/core-v6/src/abstract/JBPermissioned.sol";
+import {JBPermissions} from "@bananapus/core-v6/src/JBPermissions.sol";
+import {JBProjects} from "@bananapus/core-v6/src/JBProjects.sol";
+import {JBPermissionsData} from "@bananapus/core-v6/src/structs/JBPermissionsData.sol";
+
+contract RootPermissionBypassesPermissionIdZeroTest is Test {
+    JBProjects internal projects;
+    JBPermissions internal permissions;
+
+    address internal alice = makeAddr("alice");
+    address internal operator = makeAddr("operator");
+
+    function setUp() public {
+        permissions = new JBPermissions(address(0));
+        projects = new JBProjects(address(this), address(0), address(0));
+    }
+
+    /// @notice After M-39 fix: ROOT operator is rejected when permissionId=0 (direct-owner-only mode).
+    function test_rootPermissionRejectedWhenPermissionIdIsZero() public {
+        uint256 projectId = projects.createFor(alice);
+        MockOwnable ownable = new MockOwnable(projects, permissions, address(0), uint88(projectId));
+
+        // Grant ROOT permission (id=1) to operator.
+        uint8[] memory permissionIds = new uint8[](1);
+        permissionIds[0] = 1;
+
+        vm.prank(alice);
+        permissions.setPermissionsFor(
+            alice, JBPermissionsData({operator: operator, projectId: uint56(projectId), permissionIds: permissionIds})
+        );
+
+        (, uint88 storedProjectId, uint8 permissionId) = ownable.jbOwner();
+        assertEq(storedProjectId, projectId);
+        assertEq(permissionId, 0, "expected direct-owner-only mode");
+
+        // Operator should be rejected when permissionId=0.
+        vm.prank(operator);
+        vm.expectRevert(
+            abi.encodeWithSelector(JBPermissioned.JBPermissioned_Unauthorized.selector, alice, operator, projectId, 0)
+        );
+        ownable.protectedMethod();
+    }
+
+    /// @notice Direct owner still works when permissionId=0.
+    function test_directOwnerStillWorksWithPermissionIdZero() public {
+        uint256 projectId = projects.createFor(alice);
+        MockOwnable ownable = new MockOwnable(projects, permissions, address(0), uint88(projectId));
+
+        (, uint88 storedProjectId, uint8 permissionId) = ownable.jbOwner();
+        assertEq(storedProjectId, projectId);
+        assertEq(permissionId, 0);
+
+        // Alice (project owner) should still be able to call the protected method.
+        vm.prank(alice);
+        ownable.protectedMethod();
+    }
+
+    /// @notice Non-zero permissionId still delegates correctly via the permission system.
+    function test_delegatedOperatorWorksWhenPermissionIdNonZero() public {
+        uint256 projectId = projects.createFor(alice);
+        MockOwnable ownable = new MockOwnable(projects, permissions, address(0), uint88(projectId));
+
+        // Set permissionId to 42 (non-zero = delegation enabled).
+        vm.prank(alice);
+        ownable.setPermissionId(42);
+
+        // Grant permission 42 to operator.
+        uint8[] memory permissionIds = new uint8[](1);
+        permissionIds[0] = 42;
+
+        vm.prank(alice);
+        permissions.setPermissionsFor(
+            alice, JBPermissionsData({operator: operator, projectId: uint56(projectId), permissionIds: permissionIds})
+        );
+
+        // Operator should succeed with matching permissionId.
+        vm.prank(operator);
+        ownable.protectedMethod();
+    }
+}