Skip to content

📝 RFC: one declarative authorization point for the push broker, proxy writes and tool grants, with a decision audit event and scoped credentials #18988

Closed

Description

@clubanderson

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)

The gap

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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 effects kinds, 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

  1. 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.
  2. Decision events. Emit the record from the existing gates, allow and deny, behind a flag. Measure volume and size. No new rules.
  3. Seam. Move the gates behind the evaluation seam with parity tests proving identical decisions on the current test corpus.
  4. Operator rules, narrowing only. Add the declarative layer in report-only mode, then enforce.
  5. 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

  1. self-assigned this
    on Nov 18, 2026
  2. clubanderson commented on Nov 18, 2026

    @clubanderson
    MemberAuthor

    Claimed by the maintainer: a dispatched agent is working this, one PR to follow. Please do not open a parallel PR.

  3. hivecommons-hive commented on Nov 18, 2026

    @hivecommons-hive
    Contributor

    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 of or 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.

  4. added
    hive/partially-addressedA merged PR addressed only part of this issue; remainder still actionable
    stage/010-actionableTriaged; eligible for the hive to pick up
    stage/018-open-for-discussionOpen for discussion: proposal / design issue with no live claim; claimable, no agent work queued
    and removed
    stage/010-actionableTriaged; eligible for the hive to pick up
    on Nov 18, 2026
  5. clubanderson commented on Nov 18, 2026

    @clubanderson
    MemberAuthor

    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.

  6. github-actions commented on Nov 18, 2026

    @github-actions
    Contributor

    PR #18997 has merged (#18997) and referenced this issue with a non-closing Refs #18988 rather 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-in hive: needs-confirmation marker only when the reporter genuinely must verify before closure.

  7. added and removed
    stage/018-open-for-discussionOpen for discussion: proposal / design issue with no live claim; claimable, no agent work queued
    on Nov 18, 2026
  8. hivecommons-hive commented on Nov 18, 2026

    @hivecommons-hive
    Contributor

    Fixed by #18997 (merged 3eea465). Closing. Reply /reopen if the problem persists.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

hive/partially-addressedA merged PR addressed only part of this issue; remainder still actionable

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions