claims

# Claims Authorization Skill ## Purpose Claims-based authorization for secure agent operations and access control. ## Claim Types | Claim | Description | |-------|-------------| | `read` | Read file access | | `write` | Write file access | | `execute` | Command execution | | `spawn` | Agent spawning | | `memory` | Memory access | | `network` | Network access | | `admin` | Administrative operations | ## Commands ### Check Claim ```bash npx claude-flow claims check --agent agent-123 --claim write ``` ### Grant Claim ```bash npx claude-flow claims grant --agent agent-123 --claim write --scope "/src/**" ``` ### Revoke Claim ```bash npx claude-flow claims revoke --agent agent-123 --claim write ``` ### List Claims ```bash npx claude-flow claims list --agent agent-123 ``` ## Scope Patterns | Pattern | Description | |---------|-------------| | `*` | All resources | | `/src/**` | All files in src | | `/config/*.toml` | TOML files in config | | `memory:patterns` | Patterns namespace | ## Security Levels | Level | Claims | |-------|--------| | `minimal` | read only | | `standard` | read, write, execute | | `elevated` | + spawn, memory | | `admin` | all claims | ## Best Practices 1. Follow principle of least privilege 2. Scope claims to specific resources 3. Audit claim usage regularly 4. Revoke claims when no longer needed ## Cross-Host Work Claims (federation, v3.40.0+) Distinct from the *authorization* claims above: **work claims** coordinate *ownership of a task or resource* across agents, and now propagate across a cross-host federation so a claim made on one node is visible to the whole swarm. ### Runtime tools (local ledger) | Tool | Purpose | |------|---------| | `claims_claim` | Take ownership of an issue/resource (with optional TTL). | | `claims_release` | Give up a claim you hold. | | `claims_handoff` / `claims_accept-handoff` | Transfer a claim to another agent. | | `claims_steal` / `claims_mark-stealable` | Work-stealing for stalled claims. | | `claims_status` / `claims_list` | Inspect current ownership. | ### Federated (cross-host) Publish claim events into a federation room (`federation_bbs_publish`) so ownership converges across hosts. Message types: `ClaimIssued` / `ClaimReleased` / `ClaimHandoff` / `ClaimAck`. Rules: one owner per `resourceId`; first valid `ClaimIssued` wins (ties → earliest ts, then smallest `from`); `ClaimReleased` or expired TTL frees it; `ClaimHandoff` only from the current owner; a coordinator posts `ClaimAck` naming the authoritative owner. **Before shared work: claim, sync, and proceed only if you are the acknowledged owner.** When a claim must be both cross-host visible and runtime-enforced, mirror the two — publish the federation claim message *and* call `claims_claim`. See the `cross-host-federation` skill (ruflo-bbs-federation plugin) for the transport. ### Scoping a claim stream to a channel (ADR-386) By default every claim event lands in the shared swarm stream, where any relay member reads it. To keep a team's ownership ledger separate — or unreadable by the rest of the relay — publish claim messages into a channel instead: ``` npx ruflo federation channel --action create --name platform-team --visibility private npx ruflo federation channel --action grant --channel prv:<hex> --pubkey <teammate 64-hex> npx ruflo federation channel --action publish --channel prv:<hex> \ --type ClaimIssued --payload '{"resourceId":"repo/foo","ttlSeconds":7200}' npx ruflo federation channel --action read --channel prv:<hex> ``` Reduction rules are unchanged; only the audience changes. Two caveats before relying on it: a private channel hides content but **not metadata** (the relay still sees who published and when), and a claim nobody outside the channel can read cannot arbitrate against a claim made outside it. If ownership must be swarm-wide, keep it on the open stream. See the `open-federation` skill for channel mechanics.