@bananapus/ownable-v6 0.0.22 → 0.0.23

package/foundry.toml

@@ -14,7 +14,7 @@ depth = 100
 fail_on_revert = false
 
 [lint]
-exclude_lints = ["pascal-case-struct", "mixed-case-variable"]
+exclude_lints = ["mixed-case-variable", "pascal-case-struct"]
 [fmt]
 number_underscore = "thousands"
 multiline_func_header = "all"

package/package.json

@@ -1,18 +1,27 @@
 {
   "name": "@bananapus/ownable-v6",
-  "version": "0.0.22",
+  "version": "0.0.23",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Bananapus/nana-ownable-v6"
   },
+  "files": [
+    "CHANGELOG.md",
+    "foundry.lock",
+    "foundry.toml",
+    "references/",
+    "remappings.txt",
+    "src/",
+    "test/mocks/"
+  ],
   "engines": {
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@bananapus/core-v6": "^0.0.36",
-    "@bananapus/permission-ids-v6": "^0.0.19",
-    "@openzeppelin/contracts": "^5.6.1"
+    "@bananapus/core-v6": "0.0.38",
+    "@bananapus/permission-ids-v6": "0.0.22",
+    "@openzeppelin/contracts": "5.6.1"
   },
   "scripts": {
     "test": "forge test",

package/ADMINISTRATION.md

@@ -1,79 +0,0 @@
-# Administration
-
-## At A Glance
-
-| Item | Details |
-| --- | --- |
-| Scope | Ownership resolution primitive used by downstream repos |
-| Control posture | Primitive only; control depends on the inheriting contract |
-| Highest-risk actions | Transferring ownership to the wrong address or project and assuming delegated operators survive transfer |
-| Recovery posture | Recovery depends on the inheriting contract and the still-recognized current owner |
-
-## Purpose
-
-`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
-- delegated permission resets on ownership transfer
-
-## Roles
-
-| Role | How Assigned | Scope | Notes |
-| --- | --- | --- | --- |
-| Direct owner | Stored owner address | Per contract | Standard `Ownable`-like control |
-| Project owner | Holder of the referenced project NFT | Per contract | Dynamic ownership resolution |
-| Delegated operator | `JBPermissions` grant with the configured permission ID | Per contract and project | Only if the inheriting contract enables it |
-
-## Privileged Surfaces
-
-The meaningful control surfaces are inherited by downstream contracts:
-
-- `setPermissionId(...)`
-- `transferOwnership(...)`
-- `transferOwnershipToProject(...)`
-- `renounceOwnership()`
-- `onlyOwner` checks that resolve either the direct owner or the current project NFT holder
-
-## 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
-
-## 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
-
-## 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
-
-## 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
-
-## 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
-
-## Source Map
-
-- `src/JBOwnable.sol`
-- `src/JBOwnableOverrides.sol`
-- `src/structs/JBOwner.sol`
-- `test/OwnableInvariantTests.sol`
-- `test/OwnableEdgeCases.t.sol`
-- `test/regression/BurnLockProtection.t.sol`

package/ARCHITECTURE.md

@@ -1,92 +0,0 @@
-# Architecture
-
-## Purpose
-
-`nana-ownable-v6` adapts `Ownable` to the Juicebox model. A contract can be owned by an address or by a Juicebox project NFT, and delegated operators can satisfy `onlyOwner` through `JBPermissions`.
-
-## System Overview
-
-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
-- 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
-
-| Module | Responsibility | Notes |
-| --- | --- | --- |
-| `JBOwnable` | Familiar `onlyOwner` inheritance target | Concrete surface |
-| `JBOwnableOverrides` | Resolution, transfer, renounce, and delegated-permission logic | Core behavior |
-| `JBOwner` | Packed owner state | Shared struct |
-| `IJBOwnable` | Public interface and events | Integration surface |
-
-## Trust Boundaries
-
-- 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
-
-### Owner Check
-
-```text
-onlyOwner modifier
-  -> load packed owner state
-  -> if project-owned, resolve the current project NFT holder
-  -> otherwise use the stored owner address
-  -> accept either the resolved owner or an operator with the configured JB permission
-```
-
-## Accounting Model
-
-No treasury accounting lives here. The important state is ownership resolution data and delegated permission ID.
-
-## Security Model
-
-- 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
-
-## Canonical Checks
-
-- baseline address-owner and project-owner behavior:
-  `test/Ownable.t.sol`
-- transfer, renounce, and hostile-call edge cases:
-  `test/OwnableEdgeCases.t.sol`
-  `test/OwnableAttacks.t.sol`
-- unminted-project and burn-lock safety:
-  `test/CodexUnmintedProjectHijack.t.sol`
-  `test/regression/BurnLockProtection.t.sol`
-- ownership-state invariants:
-  `test/OwnableInvariantTests.sol`
-
-## Source Map
-
-- `src/JBOwnable.sol`
-- `src/JBOwnableOverrides.sol`
-- `src/structs/JBOwner.sol`
-- `src/interfaces/IJBOwnable.sol`
-- `test/Ownable.t.sol`
-- `test/OwnableEdgeCases.t.sol`
-- `test/OwnableAttacks.t.sol`
-- `test/CodexUnmintedProjectHijack.t.sol`
-- `test/regression/BurnLockProtection.t.sol`
-- `test/regression/ZeroAddressValidation.t.sol`
-- `test/OwnableInvariantTests.sol`
-- `references/runtime.md`
-- `references/operations.md`

package/AUDIT_INSTRUCTIONS.md

@@ -1,69 +0,0 @@
-# Audit Instructions
-
-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
-- leave dependent repos with stale or permanently wrong ownership views
-
-## Scope
-
-In scope:
-
-- `src/JBOwnable.sol`
-- `src/JBOwnableOverrides.sol`
-- `src/interfaces/`
-- `src/structs/`
-
-## Start Here
-
-1. `src/JBOwnable.sol`
-2. `src/JBOwnableOverrides.sol`
-
-## Security Model
-
-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
-
-## Roles And Privileges
-
-| Role | Powers | How constrained |
-|------|--------|-----------------|
-| Project NFT owner | Become the effective contract owner | Should update automatically with NFT transfers |
-| Override authority | Set alternative owner resolution where allowed | Must not outrank project ownership unexpectedly |
-
-## Integration Assumptions
-
-| Dependency | Assumption | What breaks if wrong |
-|------------|------------|----------------------|
-| Juicebox project ownership | NFT ownership reflects intended authority | Downstream admin checks drift from reality |
-
-## Critical Invariants
-
-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
-
-- owner resolution after project NFT transfer
-- zero-address, burn, and lock states
-- override configuration and precedence
-- downstream assumptions that cache owner state instead of re-reading it
-
-## Verification
-
-- `npm install`
-- `forge build`
-- `forge test`

package/RISKS.md

@@ -1,51 +0,0 @@
-# Juicebox Ownable Risk Register
-
-This file covers the ownership-model risks in `JBOwnable`: dynamic ownership through project NFTs, delegated owner authority, and mismatches with standard `Ownable` expectations.
-
-## How To Use This File
-
-- Read `Priority risks` first. Most failures here come from authority-model mistakes, not arithmetic bugs.
-- Use the later sections to understand what changes when ownership follows a project instead of a fixed address.
-- Treat `Invariants to verify` as the minimum proof that owner resolution stays coherent.
-
-## Priority Risks
-
-| Priority | Risk | Why it matters | Primary controls |
-|----------|------|----------------|------------------|
-| P1 | Misunderstanding dynamic owner resolution | Ownership can move when the project NFT moves or when permissions change, which breaks static `Ownable` assumptions. | Clear docs, careful integration review, and explicit tests around transfer paths. |
-| P1 | Over-broad delegated owner permissions | `JBPermissions` can broaden who effectively acts as owner. Bad configuration expands blast radius quickly. | Permission hygiene and explicit review of delegated grants. |
-| P2 | Tooling assumptions about standard `Ownable` | Some tooling assumes `owner()` maps to one address with no external permission system behind it. | Integration testing and clear documentation of the semantic differences. |
-
-## 1. Trust Assumptions
-
-- **`JBPermissions` works correctly.** A bug there affects every `JBOwnable` contract that relies on delegated owner access.
-- **`JBProjects` ownership is the source of truth.** When a contract is project-owned, whoever holds the project NFT has owner access.
-- **Delegated permission means owner-equivalent access.** Anyone granted the configured `permissionId` through `JBPermissions` can satisfy owner checks for the scoped contract.
-- **Deployment inputs are intentional.** If `initialProjectIdOwner != 0`, deployers must understand whether that project already exists.
-
-## 2. Known Risks
-
-- **Project NFT transfer changes contract ownership.** Anyone who acquires the project NFT gains owner access to contracts using that project-owned mode.
-- **Two ownership modes can confuse integrations.** Setting both `newOwner` and `projectId` is disallowed, but integrators still need to check which mode is active.
-- **`renounceOwnership` is final.** Once called, `owner()` resolves to `address(0)` and owner-gated functions stop working permanently unless a downstream contract adds its own recovery path.
-- **Constructor pre-binding can intentionally lock the contract.** If a deployer points ownership at a future project ID, `owner()` resolves to `address(0)` until that project exists.
-- **`PROJECTS == address(0)` breaks project-owned mode.** The constructor defends against this, but wrappers should still treat it as a high-signal deployment surface.
-- **Unminted project ID ownership.** Contracts using `JBOwnableOverrides` can be configured with an `initialProjectIdOwner` that references a project ID not yet minted. The first account to mint that sequential project ID will become the effective owner of the contract. Deployers must ensure the referenced project ID is already minted, or deploy the ownable contract and the project in the same transaction to prevent front-running.
-
-## 3. Accepted Behaviors
-
-- **Permission ID resets on transfer.** `permissionId` resets to `0` on ownership transfer so old delegated operators do not automatically retain power.
-- **`permissionId = 0` means direct-owner-only mode.** This is a valid configuration, not an error state.
-- **Invalid project ownership resolves fail-closed.** If `ownerOf` cannot resolve, the contract is effectively renounced until ownership becomes readable again.
-- **`transferOwnershipToProject` rejects non-existent projects.** The function checks existence at transfer time.
-- **Constructor pre-binding to a future project ID is supported.** This is useful in controlled deployment flows, but dangerous if the deployer does not control mint sequencing.
-- **Transfer events can temporarily show `address(0)`.** When ownership points to an unminted future project, the transfer event shows `address(0)` until ownership can resolve dynamically.
-
-## 4. Invariants To Verify
-
-- ownership is always exactly one of: direct address or project NFT holder
-- `_checkOwner()` reverts for all callers when the owner resolves to `address(0)`
-- `permissionId` resets to `0` on every ownership transfer
-- after `renounceOwnership()`, `jbOwner()` returns `(address(0), 0, 0)` and no address can pass `_checkOwner()`
-- `transferOwnershipToProject(projectId)` reverts for all `projectId > PROJECTS.count()` at call time
-- `initialProjectIdOwner != 0` with `PROJECTS == address(0)` always reverts during construction

package/SKILLS.md

@@ -1,41 +0,0 @@
-# Juicebox Ownable
-
-## Use This File For
-
-- 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
-
-| If you need... | Open this next |
-|---|---|
-| Repo overview and ownership model | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
-| Concrete contract | [`src/JBOwnable.sol`](./src/JBOwnable.sol) |
-| Resolution and permission logic | [`src/JBOwnableOverrides.sol`](./src/JBOwnableOverrides.sol), [`src/interfaces/`](./src/interfaces/), [`src/structs/`](./src/structs/) |
-| Runtime and migration assumptions | [`references/runtime.md`](./references/runtime.md), [`references/operations.md`](./references/operations.md) |
-| Edge, attack, and invariant coverage | [`test/Ownable.t.sol`](./test/Ownable.t.sol), [`test/OwnableEdgeCases.t.sol`](./test/OwnableEdgeCases.t.sol), [`test/OwnableAttacks.t.sol`](./test/OwnableAttacks.t.sol), [`test/OwnableInvariantTests.sol`](./test/OwnableInvariantTests.sol), [`test/CodexUnmintedProjectHijack.t.sol`](./test/CodexUnmintedProjectHijack.t.sol) |
-
-## Repo Map
-
-| Area | Where to look |
-|---|---|
-| Main contracts | [`src/`](./src/) |
-| Types | [`src/interfaces/`](./src/interfaces/), [`src/structs/`](./src/structs/) |
-| Tests | [`test/`](./test/) |
-
-## Purpose
-
-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
-
-- Open [`references/runtime.md`](./references/runtime.md) when you need owner resolution, transfer semantics, or delegated access behavior.
-- Open [`references/operations.md`](./references/operations.md) when you need migration pitfalls, test breadcrumbs, or the common stale assumptions around permission resets.
-
-## Working Rules
-
-- 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.
-- 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.