@bananapus/ownable-v6 0.0.9 → 0.0.11

package/ADMINISTRATION.md

@@ -47,7 +47,7 @@ JBOwner {
 2. If `projectId == 0`, the owner is `JBOwner.owner` directly.
 3. In both cases, `_checkOwner()` calls `_requirePermissionFrom(resolvedOwner, projectId, permissionId)`, which passes if `msg.sender` is the resolved owner OR has the configured `permissionId` granted through `JBPermissions`.
 
-**Permission delegation** uses the nana-core `JBPermissions` contract. The owner calls `JBPermissions.setPermissionsFor(...)` to grant `permissionId` to an operator address. That operator can then call any `onlyOwner` function on this contract. The ROOT permission (ID 255) in `JBPermissions` grants all permission IDs, including whatever `permissionId` is configured here.
+**Permission delegation** uses the nana-core `JBPermissions` contract. The owner calls `JBPermissions.setPermissionsFor(...)` to grant `permissionId` to an operator address. That operator can then call any `onlyOwner` function on this contract. The ROOT permission (ID 1) in `JBPermissions` grants all permission IDs, including whatever `permissionId` is configured here.
 
 **Ownership transfer resets `permissionId` to 0.** This prevents the previous owner's delegates from retaining access after a transfer. The new owner must explicitly call `setPermissionId()` to configure delegation.
 

package/AUDIT_INSTRUCTIONS.md

@@ -0,0 +1,133 @@
+# Audit Instructions -- nana-ownable-v6
+
+You are auditing a Juicebox-aware ownership module that extends OpenZeppelin's Ownable pattern. A contract inheriting `JBOwnable` can be owned by a Juicebox project (via its ERC-721 NFT) or a direct address, with delegated access through `JBPermissions`. This is a foundational access control primitive used by hooks and extensions across the Juicebox V6 ecosystem. Read [RISKS.md](./RISKS.md) first -- it documents all known risks and trust assumptions. Then come back here.
+
+## Scope
+
+**In scope -- all Solidity in `src/`:**
+```
+src/JBOwnable.sol                  # Concrete implementation with onlyOwner modifier (~76 lines)
+src/JBOwnableOverrides.sol         # Abstract base with all ownership logic (~244 lines)
+src/structs/JBOwner.sol            # Owner struct: {owner, projectId, permissionId} (~15 lines)
+src/interfaces/IJBOwnable.sol      # Interface (~47 lines)
+```
+
+**Out of scope:** Test files, JB Core contracts (`JBPermissioned`, `IJBPermissions`, `IJBProjects`), OpenZeppelin contracts, forge-std. Assume these dependencies are correct.
+
+## Architecture
+
+### Ownership Model
+
+The `JBOwner` struct packs into a single 256-bit storage slot:
+
+```solidity
+struct JBOwner {
+    address owner;       // 160 bits -- direct owner (used when projectId == 0)
+    uint88 projectId;    // 88 bits  -- JB project whose NFT holder is owner (used when != 0)
+    uint8 permissionId;  // 8 bits   -- JBPermissions ID for delegated access
+}
+```
+
+**Resolution rules:**
+1. If `projectId != 0`: owner = `PROJECTS.ownerOf(projectId)` (external call, try-catch wrapped)
+2. If `projectId == 0`: owner = `jbOwner.owner` (storage read)
+3. If the `ownerOf` call reverts (e.g., burned NFT): owner resolves to `address(0)`, effectively renouncing the contract
+
+**Delegated access:** `_checkOwner()` calls `_requirePermissionFrom(resolvedOwner, projectId, permissionId)` from `JBPermissioned`. This passes if `msg.sender == resolvedOwner` OR if `msg.sender` has the configured `permissionId` (or ROOT) in `JBPermissions`.
+
+### Inheritance Chain
+
+```
+JBOwnable (concrete)
+  extends JBOwnableOverrides (abstract)
+    extends Context (OpenZeppelin)
+    extends JBPermissioned (nana-core)
+    implements IJBOwnable (interface)
+```
+
+`JBOwnable` adds the `onlyOwner` modifier and implements `_emitTransferEvent`. `JBOwnableOverrides` contains all state management, transfer logic, and the `_checkOwner` function. Contracts that need custom `_emitTransferEvent` behavior inherit `JBOwnableOverrides` directly.
+
+### Key Functions
+
+| Function | Access | What it does |
+|----------|--------|--------------|
+| `owner()` | `public view` | Resolves and returns the current owner address. Makes an external call to `PROJECTS.ownerOf()` when project-owned. |
+| `transferOwnership(address newOwner)` | `onlyOwner` | Transfers ownership to a direct address. Reverts on `address(0)`. Resets `permissionId` to 0. |
+| `transferOwnershipToProject(uint256 projectId)` | `onlyOwner` | Transfers ownership to a JB project. Validates: non-zero, fits `uint88`, project exists (`<= PROJECTS.count()`). Resets `permissionId` to 0. |
+| `renounceOwnership()` | `onlyOwner` | Sets owner to `address(0)` and projectId to 0. Irreversible. |
+| `setPermissionId(uint8 permissionId)` | `onlyOwner` | Sets which JBPermissions ID grants delegated owner access. |
+| `_checkOwner()` | `internal view` | Resolves owner, then calls `_requirePermissionFrom`. Used by `onlyOwner` modifier. |
+| `_transferOwnership(address, uint88)` | `internal` | Core transfer logic. Updates `jbOwner`, resets `permissionId`, calls `_emitTransferEvent`. No access restriction. |
+
+## Priority Audit Areas
+
+### 1. Ownership Resolution Correctness (Highest Priority)
+
+The `owner()` and `_checkOwner()` functions both resolve ownership via the same pattern but are separate implementations (not shared helper). Verify:
+
+- **Consistency between `owner()` and `_checkOwner()`.** Both use try-catch on `PROJECTS.ownerOf()` and fall back to `address(0)` on revert. Verify they always agree on who the owner is. A divergence could allow someone to pass `_checkOwner()` while `owner()` returns a different address (or vice versa).
+- **Try-catch scope.** The try-catch catches ALL reverts from `PROJECTS.ownerOf()`, including out-of-gas. Could an attacker force an OOG in the external call to make `_checkOwner()` resolve to `address(0)`, then bypass access control? (This would require `_requirePermissionFrom(address(0), ...)` to pass, which should not be possible for any non-zero `msg.sender` unless they have ROOT permission for the project.)
+- **Zero-address as resolved owner.** When the resolved owner is `address(0)` (burned NFT or renounced), `_requirePermissionFrom(address(0), projectId, permissionId)` should revert for any caller. Verify this holds in `JBPermissioned` -- specifically that `msg.sender != address(0)` and no permission is granted to `address(0)`.
+
+### 2. Ownership Transfer State Machine
+
+Ownership transitions must be airtight:
+
+- **Mutual exclusivity.** `_transferOwnership(address newOwner, uint88 projectId)` reverts if both are non-zero. Verify there is no code path that sets both `jbOwner.owner` and `jbOwner.projectId` to non-zero values simultaneously.
+- **Permission reset.** Every ownership transfer resets `permissionId` to 0. Verify this happens in `_transferOwnership` (it does -- the entire `JBOwner` struct is overwritten). Verify there is no path to transfer ownership without going through `_transferOwnership`.
+- **Constructor validation.** The constructor rejects `(address(0), 0)` as initial owner (both zero). It also rejects `(non-zero projectId, address(0) projects)`. Verify these are the only two invalid initial states.
+- **Project existence check.** `transferOwnershipToProject` checks `projectId <= PROJECTS.count()`. Verify this prevents transferring to a non-existent project. Note: `PROJECTS.count()` returns the total number of projects ever created, and project IDs are sequential starting from 1.
+
+### 3. Permission Delegation Security
+
+`_checkOwner()` delegates to `_requirePermissionFrom(resolvedOwner, projectId, permissionId)`. Verify:
+
+- **When `permissionId == 0`.** Permission ID 0 is forbidden in `JBPermissions` (cannot be set). This means when `permissionId` is 0 (the default after any transfer), ONLY the resolved owner or ROOT holders can pass `_checkOwner()`. Delegated access is effectively disabled until `setPermissionId()` is called.
+- **ROOT override.** ROOT (permission ID 1) always grants access via `_requirePermissionFrom`. An address with ROOT for the relevant project can act as owner of any `JBOwnable` contract owned by that project, regardless of the configured `permissionId`. Verify this is intentional and documented.
+- **Wildcard project ID.** Permissions granted with `projectId = 0` in `JBPermissions` apply to all projects. Verify that a wildcard ROOT grant (which `JBPermissions` should reject) cannot be used to bypass `_checkOwner()`.
+
+### 4. Renunciation Edge Cases
+
+- **Renouncing when project-owned.** If `projectId != 0` and the NFT holder calls `renounceOwnership()`, both `owner` and `projectId` are set to 0. Verify the NFT holder can still call `renounceOwnership()` (passes `_checkOwner` with the project-resolved owner).
+- **Renouncing after NFT burn.** If the project NFT is burned (hypothetically -- JBProjects V6 has no burn), `owner()` returns `address(0)`, making `_checkOwner()` revert for everyone. The contract is effectively renounced without anyone calling `renounceOwnership()`. Verify this state is consistent and cannot be escaped.
+- **Double renounce.** After renouncing, calling `renounceOwnership()` again should revert because `_checkOwner()` will fail (resolved owner is `address(0)` and `msg.sender` cannot be `address(0)`).
+
+### 5. Storage Slot Packing
+
+The `JBOwner` struct fits in a single 256-bit slot: `address` (160) + `uint88` (88) + `uint8` (8) = 256. Verify:
+- The Solidity compiler lays out the struct as expected (no padding gaps).
+- The `_transferOwnership` function writes the entire struct atomically (`jbOwner = JBOwner({...})`), preventing partial-write inconsistencies.
+
+## Invariants to Verify
+
+1. **Mutual exclusivity**: At no point can both `jbOwner.owner != address(0)` and `jbOwner.projectId != 0`.
+2. **Transfer resets permission**: After any call to `_transferOwnership`, `jbOwner.permissionId == 0`.
+3. **Renounce is terminal**: After `renounceOwnership()`, `jbOwner.owner == address(0)` AND `jbOwner.projectId == 0` AND all subsequent `_checkOwner()` calls revert.
+4. **owner() consistency**: `owner()` and the resolved owner in `_checkOwner()` always agree.
+5. **No unauthorized transfer**: Only addresses passing `_checkOwner()` can call `transferOwnership`, `transferOwnershipToProject`, `renounceOwnership`, or `setPermissionId`.
+
+## Testing Setup
+
+```bash
+cd nana-ownable-v6
+npm install
+forge build
+forge test
+
+# Run attack scenarios
+forge test --match-contract OwnableAttacks -vvv
+
+# Run edge cases
+forge test --match-contract OwnableEdgeCases -vvv
+
+# Run invariant tests
+forge test --match-contract OwnableInvariant -vvv
+
+# Run regression tests
+forge test --match-path test/regression/ -vvv
+
+# Write a PoC
+forge test --match-path test/audit/ExploitPoC.t.sol -vvv
+```
+
+Go break it.

package/CHANGE_LOG.md

@@ -0,0 +1,229 @@
+# nana-ownable-v6 Changelog (v5 → v6)
+
+This document describes all changes between `nana-ownable` (v5) and `nana-ownable-v6` (v6).
+
+---
+
+## 1. Breaking Changes
+
+### Solidity Version Pinned
+
+All contracts changed from `pragma solidity ^0.8.23` (floating) to `pragma solidity 0.8.26` (pinned). This means v6 can only compile with Solidity 0.8.26 exactly.
+
+**Affected files:** `JBOwnable.sol`, `JBOwnableOverrides.sol`
+
+### Import Paths Updated
+
+All imports reference `@bananapus/core-v6` instead of `@bananapus/core-v5`. Any project depending on `nana-ownable` must also migrate to `nana-core-v6`.
+
+### `owner()` Returns `address(0)` Instead of Reverting for Invalid Projects
+
+In v5, if a project NFT was burned or otherwise invalid, `owner()` would revert because `PROJECTS.ownerOf()` reverts for nonexistent tokens.
+
+In v6, `owner()` wraps the call in `try-catch` and returns `address(0)` if `ownerOf()` reverts. This changes the observable behavior: callers that previously relied on a revert to detect invalid project ownership will now receive `address(0)` instead.
+
+### `_checkOwner()` Behavior Change for Invalid Projects
+
+In v5, `_checkOwner()` would revert with the ERC-721 "nonexistent token" error if the owning project NFT was burned.
+
+In v6, it resolves the owner to `address(0)` via `try-catch` and then passes `address(0)` to `_requirePermissionFrom`. This still causes a revert (no one can authenticate as `address(0)`), but the revert reason changes from an ERC-721 error to a permissions error.
+
+### `transferOwnershipToProject()` Now Validates Project Existence
+
+In v6, `transferOwnershipToProject()` checks `projectId > PROJECTS.count()` and reverts with `JBOwnableOverrides_ProjectDoesNotExist()` if the project has not been created yet. In v5, no such check existed, so ownership could be transferred to a nonexistent project ID.
+
+### Constructor Validates `PROJECTS` Address for Project-Based Ownership
+
+In v6, the constructor reverts with `JBOwnableOverrides_ZeroAddressProjectsWithProjectOwner()` if `initialProjectIdOwner != 0` and `address(projects) == address(0)`. In v5, this combination was silently accepted, which would permanently break ownership resolution since `ownerOf()` calls on `address(0)` would always revert.
+
+### `IJBOwnable` Return Name Changes
+
+The second return value of `jbOwner()` was renamed from `projectOwner` (v5) to `projectId` (v6) in the interface. The type (`uint88`) and position are unchanged, so the ABI is identical, but code referencing the named return will need updating.
+
+Additionally, `PROJECTS()` and `owner()` gained named return values in the interface:
+
+- `PROJECTS()`: `returns (IJBProjects)` (v5) -> `returns (IJBProjects projects)` (v6)
+- `owner()`: `returns (address)` (v5) -> `returns (address owner)` (v6)
+
+These are ABI-compatible but change the Solidity-level interface signature.
+
+---
+
+## 2. New Features
+
+### Defensive `try-catch` on All `PROJECTS.ownerOf()` Calls
+
+Every call to `PROJECTS.ownerOf()` in v6 is wrapped in a `try-catch` block. If the call reverts (e.g., burned NFT, broken ERC-721 implementation), the resolved owner falls back to `address(0)`. This applies to:
+
+- `owner()` -- returns `address(0)` instead of reverting.
+- `_checkOwner()` -- resolves to `address(0)`, causing a permissions revert.
+- `_transferOwnership(address, uint88)` -- resolves old owner to `address(0)` for the transfer event.
+
+### Project Existence Validation on `transferOwnershipToProject()`
+
+`transferOwnershipToProject()` now calls `PROJECTS.count()` to verify the target project exists before transferring ownership, preventing accidental loss of contract control by transferring to a nonexistent project.
+
+### Constructor Guard Against Zero-Address `PROJECTS` with Project Ownership
+
+A new constructor check prevents deploying with `projects == address(0)` when `initialProjectIdOwner != 0`, which would make ownership irrecoverable.
+
+### Comprehensive NatSpec Documentation on `IJBOwnable`
+
+The v6 interface adds full NatSpec documentation for all events, functions, parameters, and return values. The v5 interface had no NatSpec comments at all.
+
+---
+
+## 3. Event Changes
+
+No event signatures changed. Both versions define the same two events with identical parameters and indexing:
+
+- `OwnershipTransferred(address indexed previousOwner, address indexed newOwner, address caller)`
+- `PermissionIdChanged(uint8 newId, address caller)`
+
+The only difference is the addition of NatSpec documentation on both events in v6's `IJBOwnable.sol`, and the declaration order was swapped (v5: `PermissionIdChanged` first, then `OwnershipTransferred`; v6: `OwnershipTransferred` first, then `PermissionIdChanged`).
+
+---
+
+## 4. Error Changes
+
+### New Errors
+
+| Error | Contract | Description |
+|---|---|---|
+| `JBOwnableOverrides_ProjectDoesNotExist()` | `JBOwnableOverrides` | Reverts in `transferOwnershipToProject()` if `projectId > PROJECTS.count()`. |
+| `JBOwnableOverrides_ZeroAddressProjectsWithProjectOwner()` | `JBOwnableOverrides` | Reverts in constructor if `initialProjectIdOwner != 0` and `address(projects) == address(0)`. |
+
+### Unchanged Errors
+
+| Error | Status |
+|---|---|
+| `JBOwnableOverrides_InvalidNewOwner()` | Unchanged -- still used for zero-address owner, zero project ID, and dual-set owner+project scenarios. |
+
+---
+
+## 5. Struct Changes
+
+### `JBOwner` (unchanged)
+
+The struct itself is identical in both versions:
+
+```solidity
+struct JBOwner {
+    address owner;
+    uint88 projectId;
+    uint8 permissionId;
+}
+```
+
+The only difference is the addition of a `// forge-lint: disable-next-line(pascal-case-struct)` comment in v6.
+
+---
+
+## 6. Implementation Changes (Non-Interface)
+
+### `JBOwnableOverrides._checkOwner()` -- Refactored Owner Resolution
+
+**v5:**
+```solidity
+function _checkOwner() internal view virtual {
+    JBOwner memory ownerInfo = jbOwner;
+    _requirePermissionFrom({
+        account: ownerInfo.projectId == 0 ? ownerInfo.owner : PROJECTS.ownerOf(ownerInfo.projectId),
+        projectId: ownerInfo.projectId,
+        permissionId: ownerInfo.permissionId
+    });
+}
+```
+
+**v6:**
+```solidity
+function _checkOwner() internal view virtual {
+    JBOwner memory ownerInfo = jbOwner;
+    address resolvedOwner;
+    if (ownerInfo.projectId == 0) {
+        resolvedOwner = ownerInfo.owner;
+    } else {
+        try PROJECTS.ownerOf(ownerInfo.projectId) returns (address projectOwner) {
+            resolvedOwner = projectOwner;
+        } catch {
+            resolvedOwner = address(0);
+        }
+    }
+    _requirePermissionFrom({
+        account: resolvedOwner, projectId: ownerInfo.projectId, permissionId: ownerInfo.permissionId
+    });
+}
+```
+
+The ternary expression is replaced with an explicit `if/else` block and `try-catch` for defensive error handling.
+
+### `JBOwnableOverrides.owner()` -- Try-Catch on Project Lookup
+
+**v5:**
+```solidity
+return PROJECTS.ownerOf(ownerInfo.projectId);
+```
+
+**v6:**
+```solidity
+try PROJECTS.ownerOf(ownerInfo.projectId) returns (address projectOwner) {
+    return projectOwner;
+} catch {
+    return address(0);
+}
+```
+
+### `JBOwnableOverrides._transferOwnership(address, uint88)` -- Try-Catch on Old Owner Lookup
+
+**v5:**
+```solidity
+address oldOwner = ownerInfo.projectId == 0 ? ownerInfo.owner : PROJECTS.ownerOf(ownerInfo.projectId);
+```
+
+**v6:**
+```solidity
+address oldOwner;
+if (ownerInfo.projectId == 0) {
+    oldOwner = ownerInfo.owner;
+} else {
+    try PROJECTS.ownerOf(ownerInfo.projectId) returns (address projectOwner) {
+        oldOwner = projectOwner;
+    } catch {
+        oldOwner = address(0);
+    }
+}
+```
+
+### Named Arguments Used Throughout
+
+All internal function calls in v6 use named arguments (e.g., `_transferOwnership({newOwner: initialOwner, projectId: initialProjectIdOwner})`) instead of positional arguments. This is a style-only change with no behavioral impact.
+
+### NatSpec Improvements
+
+- `JBOwnable._emitTransferEvent()`: Incomplete comment in v5 (`"some contracts will try to deploy contracts for a project before"`) is completed in v6 (`"some contracts need to deploy contracts for a project before the project's NFT has been minted, so the transfer event resolves the project's current owner at emission time."`). A new `@dev` comment also explains why this function intentionally does NOT use try-catch (unlike `_transferOwnership`): reverting on a nonexistent new project is desirable to prevent transferring ownership to an invalid project.
+- `JBOwnableOverrides._emitTransferEvent()`: Added `@param` tags for `previousOwner`, `newOwner`, and `newProjectId`.
+- `renounceOwnership()`, `setPermissionId()`: Changed `@notice This can only be called by the current owner.` to `@dev`.
+- `transferOwnership()`, `transferOwnershipToProject()`: Added documentation about `permissionId` being reset to 0 on transfer.
+- Constructor `@param initialOwner`: Fixed typo `intialProjectIdOwner` to `initialProjectIdOwner`.
+
+### Comment/Formatting Fixes
+
+- Fixed malformed section header comment in v5 (`custom errors --------------------------//b`) to properly formatted (`custom errors ------------------------- //`).
+
+---
+
+## 7. Migration Table
+
+| v5 | v6 | Change Type |
+|---|---|---|
+| `pragma solidity ^0.8.23` | `pragma solidity 0.8.26` | Pinned compiler version |
+| `@bananapus/core-v5` imports | `@bananapus/core-v6` imports | Dependency upgrade |
+| `PROJECTS.ownerOf()` called directly | `try PROJECTS.ownerOf() catch` in `owner()`, `_checkOwner()`, `_transferOwnership()` | Defensive error handling |
+| `transferOwnershipToProject()` -- no existence check | Reverts with `JBOwnableOverrides_ProjectDoesNotExist()` if `projectId > PROJECTS.count()` | New validation |
+| Constructor allows `projects == address(0)` with `initialProjectIdOwner != 0` | Reverts with `JBOwnableOverrides_ZeroAddressProjectsWithProjectOwner()` | New validation |
+| `IJBOwnable.jbOwner()` returns `(address owner, uint88 projectOwner, uint8 permissionId)` | Returns `(address owner, uint88 projectId, uint8 permissionId)` | Return name change (ABI compatible) |
+| `IJBOwnable.PROJECTS()` returns `(IJBProjects)`, `owner()` returns `(address)` | Returns `(IJBProjects projects)`, `(address owner)` | Named return values added (ABI compatible) |
+| `IJBOwnable` -- no NatSpec | Full NatSpec on all events, functions, params, and returns | Documentation |
+| Positional arguments in internal calls | Named arguments throughout | Style only |
+| 1 custom error | 3 custom errors (`+ ProjectDoesNotExist`, `+ ZeroAddressProjectsWithProjectOwner`) | New errors |
+| `JBOwner` struct | Identical (added forge-lint comment only) | No change |

package/RISKS.md

@@ -1,23 +1,21 @@
-# nana-ownable-v6 — Risks
+# RISKS.md -- nana-ownable-v6
 
-## Trust Assumptions
+## 1. Trust Assumptions
 
-1. **JBPermissions** — Permission checks delegate to JBPermissions contract. A bug in JBPermissions affects all JBOwnable contracts.
-2. **JBProjects ERC-721** — When owned by a project, ownership follows the ERC-721 token. Whoever holds the project NFT has owner access.
-3. **Permission Delegation** — Anyone granted the configured `permissionId` via JBPermissions gets owner-equivalent access.
+- **JBPermissions.** Permission checks delegate to JBPermissions contract. A bug in JBPermissions affects all JBOwnable contracts.
+- **JBProjects ERC-721.** When owned by a project, ownership follows the ERC-721 token. Whoever holds the project NFT has owner access.
+- **Permission Delegation.** Anyone granted the configured `permissionId` via JBPermissions gets owner-equivalent access for the scoped function.
 
-## Known Risks
+## 2. Known Risks
 
-| Risk | Description | Mitigation |
-|------|-------------|------------|
-| Permission escalation | Granting `permissionId` gives full owner access to that function | Only grant to trusted operators |
-| Project NFT transfer | Transferring the project NFT transfers ownership of all JBOwnable contracts tied to it | Intentional design; use multisig for project NFT |
-| Renounce is permanent | `renounceOwnership()` is irreversible | Standard OpenZeppelin pattern |
-| Zero address project | Setting `projectId = 0` with `owner = address(0)` permanently locks ownership | Validate before calling |
+- **Project NFT transfer = ownership transfer.** If ownership is tied to a project ID, anyone who acquires the project NFT (via transfer, marketplace purchase, or social engineering) gains full owner access to all contracts using that JBOwnable instance. Project NFT holders must treat the NFT as a high-value key.
+- **Permission ID reset on transfer.** `permissionId` resets to 0 on ownership transfer, which could temporarily lock out delegated operators. By design -- prevents permission clashes for new owners.
+- **Burned/invalid project NFT.** If the project NFT is burned or `ownerOf` reverts, the contract is effectively renounced (owner resolves to `address(0)`). Defensive try-catch in `owner()` and `_checkOwner()`. JBProjects V6 has no burn function, so this is a defensive measure.
+- **Dual ownership ambiguity.** Setting both `newOwner` and `projectId` to non-zero reverts, but the two-mode design could confuse integrators about which mode is active. `jbOwner()` exposes both fields for inspection.
+- **`transferOwnershipToProject` with future project.** Checks `projectId > PROJECTS.count()` to prevent transferring to non-existent projects.
 
-## Privileged Roles
+## 3. Invariants to Verify
 
-| Role | Access | Scope |
-|------|--------|-------|
-| Owner (address or project holder) | All `onlyOwner` functions | Per-contract |
-| Permission delegates | `onlyOwner` functions via JBPermissions | Per-contract, per-permissionId |
+- Ownership is always exactly one of: direct address OR project NFT holder (never both, never neither unless renounced).
+- `_checkOwner()` reverts for all callers when the owner resolves to `address(0)`.
+- `permissionId` is correctly reset to 0 on every ownership transfer.

package/USER_JOURNEYS.md

@@ -0,0 +1,245 @@
+# User Journeys -- nana-ownable-v6
+
+Concrete end-to-end flows through the JBOwnable system. Each journey traces the exact function calls, state changes, and external interactions.
+
+## Journey 1: Deploy a Project-Owned Contract
+
+**Actor:** Protocol developer deploying a hook or extension that should be owned by a Juicebox project.
+**Goal:** Create a contract where the project NFT holder has owner access.
+
+### Precondition
+
+A Juicebox project exists with ID `projectId`. The `JBProjects` and `JBPermissions` contracts are deployed.
+
+### Steps
+
+1. **Developer deploys a contract inheriting `JBOwnable`**
+
+   ```solidity
+   new MyHook(permissions, projects, address(0), projectId)
+   ```
+
+   - `initialOwner = address(0)` because ownership is project-based
+   - `initialProjectIdOwner = projectId`
+
+2. **Constructor execution in `JBOwnableOverrides`**
+
+   - Stores `PROJECTS = projects` (immutable)
+   - Validates: `initialProjectIdOwner != 0` AND `address(projects) != address(0)` -- passes
+   - Validates: not both zero (passes because `initialProjectIdOwner != 0`)
+   - Calls `_transferOwnership(address(0), projectId)`:
+     - Sets `jbOwner = JBOwner({owner: address(0), projectId: projectId, permissionId: 0})`
+     - Calls `_emitTransferEvent(address(0), address(0), projectId)`
+   - In `JBOwnable._emitTransferEvent`: emits `OwnershipTransferred(address(0), PROJECTS.ownerOf(projectId), msg.sender)`
+
+3. **Ownership is now live**
+
+   - `owner()` calls `PROJECTS.ownerOf(projectId)` and returns the current NFT holder
+   - `_checkOwner()` validates `msg.sender` against the NFT holder (or permission delegates)
+
+### Result
+
+The contract is owned by whichever address holds the project NFT. If the NFT is transferred, ownership automatically follows -- no on-chain update to the JBOwnable contract is needed.
+
+### What to verify
+
+- `jbOwner.owner == address(0)` and `jbOwner.projectId == projectId` after construction.
+- `jbOwner.permissionId == 0` (no delegated access until explicitly configured).
+- `owner()` returns the current NFT holder, not a cached value.
+- If the project does not exist (ID > `PROJECTS.count()`), the constructor still succeeds -- the existence check is only enforced in `transferOwnershipToProject`, not the constructor. Verify whether this is safe (the deployer presumably knows the project exists).
+
+---
+
+## Journey 2: Transfer Ownership to a Different Address
+
+**Actor:** Current owner (direct address or project NFT holder).
+**Goal:** Transfer ownership from the current owner to a new direct address.
+
+### Precondition
+
+The caller is the current owner or has the configured `permissionId` (or ROOT) via `JBPermissions`.
+
+### Steps
+
+1. **Owner calls `transferOwnership(newOwner)`**
+
+   - `newOwner` must not be `address(0)` (reverts with `JBOwnableOverrides_InvalidNewOwner`)
+
+2. **`_checkOwner()` validates the caller**
+
+   - Resolves the current owner (via `PROJECTS.ownerOf()` if project-owned, or `jbOwner.owner` if address-owned)
+   - Calls `_requirePermissionFrom(resolvedOwner, projectId, permissionId)`
+   - Passes if `msg.sender == resolvedOwner` OR `msg.sender` has the required permission
+
+3. **`_transferOwnership(newOwner, 0)` executes the transfer**
+
+   - Records `oldOwner` (resolved from current `jbOwner`)
+   - Overwrites `jbOwner = JBOwner({owner: newOwner, projectId: 0, permissionId: 0})`
+   - Calls `_emitTransferEvent(oldOwner, newOwner, 0)`
+
+4. **`_emitTransferEvent` in `JBOwnable`**
+
+   - Since `newProjectId == 0`: emits `OwnershipTransferred(oldOwner, newOwner, msg.sender)`
+
+### Result
+
+`jbOwner.owner == newOwner`, `jbOwner.projectId == 0`, `jbOwner.permissionId == 0`. The new owner must call `setPermissionId()` to re-enable delegated access.
+
+### What to verify
+
+- If the contract was previously project-owned, `projectId` is now 0 (project ownership is cleared).
+- `permissionId` is reset to 0, revoking all previously delegated permissions.
+- The previous owner (or their delegates) can no longer call `onlyOwner` functions.
+- `newOwner` can immediately call `onlyOwner` functions without any additional setup.
+
+---
+
+## Journey 3: Transfer Ownership to a Juicebox Project
+
+**Actor:** Current owner (direct address or project NFT holder).
+**Goal:** Transfer ownership from the current owner to a Juicebox project, so the NFT holder becomes the new owner.
+
+### Precondition
+
+The target project exists (ID <= `PROJECTS.count()`). The caller is the current owner or has adequate permissions.
+
+### Steps
+
+1. **Owner calls `transferOwnershipToProject(projectId)`**
+
+   - Validates: `projectId != 0` (reverts with `JBOwnableOverrides_InvalidNewOwner`)
+   - Validates: `projectId <= type(uint88).max` (reverts with `JBOwnableOverrides_InvalidNewOwner`)
+   - Validates: `projectId <= PROJECTS.count()` (reverts with `JBOwnableOverrides_ProjectDoesNotExist`)
+
+2. **`_checkOwner()` validates the caller** (same as Journey 2, Step 2)
+
+3. **`_transferOwnership(address(0), uint88(projectId))` executes the transfer**
+
+   - Records `oldOwner` (resolved from current `jbOwner`)
+   - Overwrites `jbOwner = JBOwner({owner: address(0), projectId: uint88(projectId), permissionId: 0})`
+   - Calls `_emitTransferEvent(oldOwner, address(0), uint88(projectId))`
+
+4. **`_emitTransferEvent` in `JBOwnable`**
+
+   - Since `newProjectId != 0`: emits `OwnershipTransferred(oldOwner, PROJECTS.ownerOf(projectId), msg.sender)`
+
+### Result
+
+`jbOwner.owner == address(0)`, `jbOwner.projectId == projectId`, `jbOwner.permissionId == 0`. The project NFT holder is now the owner. Ownership dynamically follows NFT transfers.
+
+### What to verify
+
+- The project existence check (`projectId <= PROJECTS.count()`) prevents transferring to a nonexistent project.
+- The `uint88` cast does not truncate (the preceding `type(uint88).max` check ensures this).
+- If the project NFT is subsequently burned (hypothetically), `owner()` returns `address(0)` and the contract is effectively renounced.
+
+---
+
+## Journey 4: Delegate Access via Permission ID
+
+**Actor:** Current owner.
+**Goal:** Allow additional addresses to call `onlyOwner` functions through the JBPermissions system.
+
+### Precondition
+
+The contract has an owner. The owner wants to delegate access to one or more operators.
+
+### Steps
+
+1. **Owner calls `setPermissionId(permissionId)`**
+
+   - `_checkOwner()` validates the caller
+   - `_setPermissionId(permissionId)` writes `jbOwner.permissionId = permissionId`
+   - Emits `PermissionIdChanged(permissionId, msg.sender)`
+
+2. **Owner grants the permission to operators via JBPermissions**
+
+   - `permissions.setPermissionsFor(account, JBPermissionsData({operator: operatorAddress, projectId: projectId, permissionIds: [permissionId]}))`
+   - This is an external call on the JBPermissions contract, not on the JBOwnable contract
+
+3. **Operator calls an `onlyOwner` function**
+
+   - `_checkOwner()` resolves the owner and calls `_requirePermissionFrom(resolvedOwner, projectId, permissionId)`
+   - `JBPermissioned._requirePermissionFrom` checks `JBPermissions.hasPermission(msg.sender, resolvedOwner, projectId, permissionId)` -- passes
+
+### Result
+
+The operator can call any function protected by `onlyOwner` on this contract. The permission is scoped to the owner's account and project ID.
+
+### What to verify
+
+- `permissionId == 0` effectively disables delegation (permission ID 0 cannot be set in `JBPermissions`). Only the owner (or ROOT holders) can call `onlyOwner` functions.
+- If the owner transfers ownership, `permissionId` resets to 0. The new owner must re-configure delegation.
+- ROOT (permission ID 1) always grants access regardless of the configured `permissionId`. This is a feature of `JBPermissioned`, not specific to `JBOwnable`.
+- The operator's access is not stored on the JBOwnable contract -- it lives in JBPermissions. Changing the `permissionId` on JBOwnable instantly changes which JBPermissions grants are recognized.
+
+---
+
+## Journey 5: Renounce Ownership
+
+**Actor:** Current owner.
+**Goal:** Permanently give up ownership, making `onlyOwner` functions uncallable.
+
+### Precondition
+
+The caller is the current owner and understands this action is irreversible.
+
+### Steps
+
+1. **Owner calls `renounceOwnership()`**
+
+   - `_checkOwner()` validates the caller
+
+2. **`_transferOwnership(address(0), 0)` executes**
+
+   - Records `oldOwner` (resolved from current `jbOwner`)
+   - Overwrites `jbOwner = JBOwner({owner: address(0), projectId: 0, permissionId: 0})`
+   - Calls `_emitTransferEvent(oldOwner, address(0), 0)`
+   - Emits `OwnershipTransferred(oldOwner, address(0), msg.sender)`
+
+### Result
+
+`jbOwner` is zeroed out. `owner()` returns `address(0)`. All future calls to `_checkOwner()` revert because `_requirePermissionFrom(address(0), 0, 0)` fails for any `msg.sender` (no address equals `address(0)`, and no permission can satisfy the check against a zero-address account).
+
+### What to verify
+
+- After renouncing, `transferOwnership`, `transferOwnershipToProject`, `setPermissionId`, and `renounceOwnership` all revert.
+- There is no recovery mechanism. No admin backdoor. No timelock. Renouncement is permanent.
+- A second call to `renounceOwnership()` also reverts (because `_checkOwner()` fails).
+- Even ROOT holders cannot act as owner after renouncement, because `_requirePermissionFrom(address(0), 0, 0)` does not recognize ROOT as a valid bypass when the account is `address(0)`.
+
+---
+
+## Journey 6: Implicit Renouncement via Project NFT Burn
+
+**Actor:** None (system behavior).
+**Goal:** Understand what happens when the project NFT underlying a project-owned contract ceases to exist.
+
+### Precondition
+
+The contract is project-owned (`jbOwner.projectId != 0`). The project NFT is burned or otherwise invalidated (note: JBProjects V6 has no burn function, so this is a defensive scenario).
+
+### Steps
+
+1. **`PROJECTS.ownerOf(projectId)` starts reverting**
+
+   - The ERC-721 `ownerOf` function reverts for burned tokens
+
+2. **`owner()` catches the revert and returns `address(0)`**
+
+   - The try-catch in `owner()` returns `address(0)` when `ownerOf` reverts
+
+3. **`_checkOwner()` catches the revert and resolves owner to `address(0)`**
+
+   - `_requirePermissionFrom(address(0), projectId, permissionId)` is called
+   - No `msg.sender` can equal `address(0)`, so the check always fails
+
+### Result
+
+The contract is effectively renounced without anyone calling `renounceOwnership()`. All `onlyOwner` functions permanently revert. The `jbOwner` struct still contains the old `projectId`, but it has no practical effect.
+
+### What to verify
+
+- There is no way to "revive" ownership after the NFT is burned. Even re-minting an NFT with the same ID (if possible) would restore ownership.
+- The `jbOwner` struct is NOT cleared in this scenario -- it still shows the old `projectId`. Only the resolved owner is `address(0)`.
+- This behavior is consistent between `owner()` and `_checkOwner()` (both use the same try-catch pattern).