Repository navigation
Description
Summary
Hive's write-side authorization is correct but spread out. Which mode may do what is a Go rule table in the proxy, the push broker has its own list of protected paths and its own scans, token tiers are a fixed mapping from mode to scope, and tool approval is the one place where operators already write declarative rules. There is no single point where a request becomes a decision, so there is no single record of why something was allowed or refused, and an operator cannot express a repository- or team-specific rule without a code change.
This RFC asks whether Hive should add one declarative authorization point, evaluated at the places that already mediate writes (the proxy, the relays and the push broker), that emits one audit event per decision and issues narrowly scoped, short-lived credentials per decision. It is a design question first; the code to build it is only worth writing if the questions below have answers.
What Hive already has (so the gap is concrete)
- Mode table in code.
src/crux/proxy/rules.gomaps (method, path pattern) to a minimum mode, first match wins, with aCapabilityOR-grant (RFC: converse capability + Linear agents as first-class workspace members #4492). Autonomy per repo is applied inautonomy_levels.go; GraphQL mutations are classified ingraphql_mutation.go; Linear has its own table inlinear_rules.go; hard denies (pull request create and merge for every mode) are inrules_deny.go; write-surface enforcement is inwrite_surface_enforce.go. - Operational gates ahead of the mode chain. Per-repo pause (✨ feature: per-repo agent pause — quiet one repo without stopping the hive #6203), per-repo agent scope (✨ feature: per-repo custom agents — scope an agent definition to the repos it serves #6204), repo allowlist, per-agent GitHub budget (
agent_github_budget.go), all installed through setters ingithub_proxy_setters.go. The ordering between these and the mode chain lives in the order of statements ingithub_proxy_mitm.go. - Push broker.
src/crux/pushbroker/pushbroker.goruns a fixed sequence: empty-commit rejection, fast-forward and lease checks, forged-signoff check, protected paths (protected.go, default list or per-call override), outgoing-diff secret scan, then mints a token and pushes undereffects.Boundaryjournaling. - Credentials. A scoped token per agent tier, narrowed to repositories where known (
pushbroker.GitHubAppMinter,hivecap.TokenScoper.ScopedTokenForRepos), and an opt-in short-lived signed token for downstream verifiers (src/pkg/mint/agent.go, tiers mapped to scope strings). Hosted GitHub installation tokens cannot be narrowed to a branch, so the finest grain available from the forge is repository plus permission set. - Declarative rules, in one place. Tool approval rules are CEL expressions in config, compiled at load, with evaluation errors treated as no-match and the ACMM level applied as a ceiling after rule evaluation (
src/crux/toolapprove/rules.go, built on the same posture assrc/pkg/celtrigger, [v5] Adopt tool-approval as an explicit, ACMM-gated operation #4000). - Evidence. Denials return a machine-readable reason code (🌱 tokens: compact gh --json projection wrappers that keep gate fields; one-line denial messages (review C3) #12127), are counted per agent (
github_proxy_violations.go), and dashboard and API actions go to/data/audit.jsonl(src/docs/audit-log.md,src/pkg/agentaudit). Related designs: 📝 RFC: Hive Runtime Guardrails (v7) #12815 (runtime guardrails on tool calls), 📝 RFC: v7 - Hive for teams (shared sessions, org policy, multi-forge, entitlements, audit) #17091 (v7 team policy and audit).
The gap
- No single decision record. A denial carries a reason code and a counter increment; I found no record for an allow, and none that contains the inputs the decision used, the rule that matched and the version of the rules in force. "Why was this push allowed on that branch last Tuesday" is answered by reading code at a commit.
- Rules are code, not data. Changing a protected-path list, a path rule or a per-repo exception needs a release. Operators can toggle features and levels but cannot add a rule. Tool approval shows the declarative route works for Hive.
- Ordering is implicit. The sequence of gates in the proxy and the broker is defined by statement order, so adding a gate means reasoning about every other gate.
- Credentials are tied to tiers, not to the decision. A minted token is scoped by tier and repository, not by the specific action the decision approved (one push to one repository, one lease). The broker mints after its checks, which is the right place, but the token's life and reach are not part of the decision record.
- Error semantics differ by layer. Tool approval treats an evaluation error as no-match. For a rule that grants authority that is safe; for a rule that denies it would be an allow. The authorization point needs an explicit, per-effect error rule (deny on error for enforcement).
Proposal sketch
- One evaluation seam, a small interface called with a typed request (actor, agent mode and level, repository, action kind from the existing
effectskinds, target such as branch, paths changed, labels, repo state) and returning allow, deny or hold, with a rule id and reason code. The existing Go gates become the built-in rule set, so behaviour is unchanged until an operator adds a rule. - A declarative rule language for operator additions. Candidate: extend the CEL posture already used for approval rules (compile at load, bounded cost, ceiling applied afterwards). A rule can only narrow what the built-in floor allows, never widen it.
- One audit event per decision, allow and deny, appended to the existing audit stream, containing request attributes (no payloads or secrets), matched rule id, rules version hash, decision, latency and the credential id if one was minted. Allows on high-volume reads are sampled or aggregated by a documented rule, never silently dropped.
- Per-decision credentials. For pushes and relays the broker asks for a token narrowed to the one repository and the permission set the decision needs, with the shortest lifetime the forge allows, and records its id in the decision event. Remove token reach that no current action needs.
- Fail closed. Evaluation errors, timeouts and panics on an enforcement point are a deny. A rules file that does not load keeps the last good version and raises an alert; it never falls back to "no rules".
Phased plan
- Inventory. List every gate in the proxy, relays and push broker, with its inputs and order. Define the typed request and the decision record. No behaviour change.
- Decision events. Emit the record from the existing gates, allow and deny, behind a flag. Measure volume and size. No new rules.
- Seam. Move the gates behind the evaluation seam with parity tests proving identical decisions on the current test corpus.
- Operator rules, narrowing only. Add the declarative layer in report-only mode, then enforce.
- Credentials. Narrow minted tokens to the decision, starting with the push broker.
Open questions
- Language. Reuse the existing CEL rules and their error posture, or a different language? Is the vocabulary shared with the tool-call guardrails design in 📝 RFC: Hive Runtime Guardrails (v7) #12815, or are the two kept separate with a common decision record?
- Where the seam lives. The proxy and push broker are in the Crux module and talk to Hive through capability seams (
hivecap). Does evaluation run in the runtime, in Hive, or both, and how does the decision record cross that boundary without becoming a new trust path? - Policy source and integrity. Operator-owned file outside agent workspaces, hub-delivered bundle (📝 RFC: v7 - Hive for teams (shared sessions, org policy, multi-forge, entitlements, audit) #17091), or both? How are changes reviewed and versioned?
- Audit volume and integrity. What do allows cost at proxy request rates, and where do events live so an agent cannot alter them?
- Hold semantics. Is "hold for a human" in scope for the proxy path, or only deny and allow?
- Credential limits. If the forge cannot narrow a token below repository and permission set, how much of the per-decision credential idea is real, and how much is record-keeping?
- Migration. Which gates move first, and what is the test that proves no decision changed?
Acceptance criteria for this RFC
- A decision on the evaluation seam and the decision record schema.
- A decision on the rule language and the error semantics per effect.
- A gate inventory attached to the issue.
- Phase 2 and 3 split into task-sized issues with parity tests named.
Effort: high. It touches the proxy, the relays, the broker and the audit stream, so it is an RFC and not a task.
Activity
clubanderson commentedon Nov 18, 2026
Claimed by the maintainer: a dispatched agent is working this, one PR to follow. Please do not open a parallel PR.
📖 docs: neutralize two proxy and credential notes in the authorizatio…
📖 docs: generalize credential open question
hivecommons-hive commentedon Nov 18, 2026
Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.
PR #19098 covers this issue: #19098
The PR body says this is partial/non-closing work (
Refs/Part ofor leave-open wording), so Hive will not add a closing keyword. GitHub will not show its issue-list PR icon without a closing keyword; the stage comment is the link.📖 Design record: one authorization point for push broker, proxy write…
clubanderson commentedon Nov 18, 2026
Design document merged: https://github.com/hivecommons/hive/blob/v5/src/docs/design/authorization-decision-point.md
It inventories today's authorization decisions with code citations, proposes a single decision point with a stable decision record, and covers fail-closed behavior, audit events, scoped credentials and a phased, shadow-first migration. Open questions are listed at the end. Reviews and comments are welcome here. The RFC stays open for discussion.
github-actions commentedon Nov 18, 2026
PR #18997 has merged (#18997) and referenced this issue with a non-closing
Refs #18988rather than a closing keyword.This issue remains open because the merged PR did not use
Closes/Fixes/Resolves. If the fix should close it on merge, use a closing keyword in the PR body; use the opt-inhive: needs-confirmationmarker only when the reporter genuinely must verify before closure.🐛 authz: satisfy staticcheck and refresh shifted docs citations
hivecommons-hive commentedon Nov 18, 2026
Fixed by #18997 (merged 3eea465). Closing. Reply /reopen if the problem persists.
📖 authz: refresh shifted pushbroker line citations in the design record
🌱 chore: top up v6 from v5 (2026-11-18) (#19100)
✨ Shadow-mode authorization decision seam for the push broker's chang…