brokerkit

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 14, 2026 License: MIT Imports: 0 Imported by: 0

README

BrokerKit

BrokerKit is a monorepo and Go toolkit for brokered access-control services. It keeps protected credentials and Unix privilege boundaries in dedicated services while untrusted clients receive only narrowly scoped broker access.

This repository contains the shared runtime plus three separate broker executables:

  • HF Broker for Hugging Face credentials and Git, LFS, Hub, and inference operations.
  • GH Broker for GitHub App credentials, repository reads, Git operations, and pull requests.
  • Sudo Broker for approved exact-command execution as another Unix user.
  • OpenClaw BrokerKit, an independently packaged approvals UI and channel integration.

All brokers use BrokerKit for authentication, policy, grants, operator APIs, audit, notification state, Telegram transport, setup, and installation. Each broker remains a separate process with separate credentials and provider logic.

BrokerKit stays focused: it is not a full application framework, and it does not contain provider-specific Hugging Face, GitHub, or Unix privilege logic.

The controlplane package is the standard assembly path for grant storage, client and operator authentication, the protected operator API, audit export, and approval-channel decisions. secretfile owns the named credential format, and conformance provides the black-box contract suite consumed by every broker.

Design

The common broker shape is:

client request
        ↓
authenticate broker client
        ↓
classify request into client + operation + target + attrs
        ↓
policy decision: deny / active grant / allow / request / no_match
        ↓
optional approval grant
        ↓
provider-specific executor
        ↓
audit log

brokerkit owns the reusable control plane. Each broker still owns its dangerous domain boundary:

  • hf-broker owns Hugging Face Git/LFS, mirrors, append-only checks, and Hub token use.
  • gh-broker owns GitHub API/Git behavior, pull requests, installations, and GitHub ruleset compatibility.
  • sudo-broker owns exact cataloged Unix command execution, target identity switching, the privileged helper, and OS-specific host validation. V1 has no shell or TTY mode.

The canonical ownership boundary is in docs/OWNERSHIP.md. The security boundaries and fail-closed behavior are in docs/security/THREAT_MODEL.md. The shared install, setup, policy, grant, approval, audit, doctor, and release contract is in docs/UNIFIED_BROKER_CONTRACT.md.

Shared Packages

The main reusable packages are:

  • auth: shared-secret bearer/basic authentication for named clients
  • policy: generic rule evaluation with broker-owned operation registries
  • grants: durable short-lived grants, use reservations, crash recovery, and notification delivery state
  • agentapi, agentclient, agentconformance, grantclient, and clienthttp: shared Agent V1 server, clients and black-box contract tests, temporary-grant clients, and credential-safe HTTP defaults
  • usebudget: finite/default/unlimited approval use-budget values
  • audit: secret-safe structured audit helpers
  • httpx: proxy-safe header filtering and bounded body helpers
  • clientconfig: shared client env rendering for ~/.config/<broker>/client.env
  • setup: shared client command parsing, secret input/generation, and common systemd setup options
  • service: hardened provider-neutral systemd unit rendering
  • doctor: portable identity, root-equivalent group, service separation, and fail-closed secret-path, ACL, and mode checks with secret-safe reports
  • installer: the canonical parameterized POSIX binary installer used by thin component-local broker wrappers
  • notify: approval notification interfaces, callback answers, and a stateless Telegram adapter with send, explicit status edit, and long-poll callbacks
  • operatorinbox, operatorauth, and operatorapi: bounded safe operator projections, separate operator authority, typed decisions, and durable SSE
  • operatorclient and operatorfake: trusted-host integration and contract testing for operator applications
  • gitx: generic Git smart-HTTP parsing helpers shared by HF and GH brokers
  • store: atomic file storage and lock helpers used by grants and audit

Provider-specific execution code does not belong in brokerkit.

Status

The brokers and OpenClaw plugin use the shared Operator V1 control plane. Telegram delivery is deliberately stateless: brokers persist notification references and use brokerkit/grants to drive every status transition and retry after a restart. The shared operational runtime is described in docs/OPERATIONS_RUNTIME.md.

The operator backend and trusted web-host integration contract is documented in docs/OPERATOR_INBOX.md. The maintained documentation map is in docs/README.md.

License

MIT

Documentation

Overview

Package brokerkit contains shared primitives for broker-style access-control services.

Index

Constants

View Source 
const ModulePath = "github.com/osolmaz/brokerkit"

ModulePath is the canonical Go module path for brokerkit.

Variables

This section is empty.

Functions

func CanonicalModulePath 

func CanonicalModulePath() string

CanonicalModulePath returns the canonical Go module path for brokerkit.

Types

This section is empty.

Source Files

View all Source files

Directories

Path Synopsis
Package agentapi serves the provider-neutral Agent Operations V1 HTTP API.
 Package agentapi serves the provider-neutral Agent Operations V1 HTTP API.
Package agentclient provides the provider-neutral Agent Operations V1 client.
 Package agentclient provides the provider-neutral Agent Operations V1 client.
Package agentconformance provides reusable black-box Agent Operations V1 tests.
 Package agentconformance provides reusable black-box Agent Operations V1 tests.
Package agentops owns the provider-neutral Agent Operations V1 lifecycle.
 Package agentops owns the provider-neutral Agent Operations V1 lifecycle.
Package agentv1 defines the provider-neutral Agent Operations V1 lifecycle.
 Package agentv1 defines the provider-neutral Agent Operations V1 lifecycle.
Package agentv1wire translates generated Agent V1 wire models and domain types.
 Package agentv1wire translates generated Agent V1 wire models and domain types.
Package approval provides shared approval-channel decision handling.
 Package approval provides shared approval-channel decision handling.
Package audit writes secret-safe structured broker audit events.
 Package audit writes secret-safe structured broker audit events.
Package auth authenticates named broker clients from shared secrets.
 Package auth authenticates named broker clients from shared secrets.
Package authorization coordinates policy decisions and durable approval requests.
 Package authorization coordinates policy decisions and durable approval requests.
brokers
github/cmd/generate-github-surfaces command
github/cmd/gh-broker command
github/internal/appmanifest
Package appmanifest generates minimum GitHub App permission manifests.
 Package appmanifest generates minimum GitHub App permission manifests.
github/internal/approval
Package approval renders GitHub-specific operator approval details.
 Package approval renders GitHub-specific operator approval details.
github/internal/config
github/internal/ghplan
Package ghplan owns immutable GitHub execution plans.
 Package ghplan owns immutable GitHub execution plans.
github/internal/githubauth
Package githubauth owns every GitHub credential used by gh-broker.
 Package githubauth owns every GitHub credential used by gh-broker.
github/internal/githubdoctor
Package githubdoctor verifies local isolation and GitHub-native enforcement.
 Package githubdoctor verifies local isolation and GitHub-native enforcement.
github/internal/githubsurface
Package githubsurface validates the complete generated GitHub operation surface.
 Package githubsurface validates the complete generated GitHub operation surface.
github/internal/graphqlmanifest
Package graphqlmanifest owns reviewed persisted GitHub GraphQL documents.
 Package graphqlmanifest owns reviewed persisted GitHub GraphQL documents.
github/internal/httpapi
github/internal/inventory
Package inventory owns exhaustive dispositions for pinned GitHub surfaces.
 Package inventory owns exhaustive dispositions for pinned GitHub surfaces.
github/internal/mcpcatalog
Package mcpcatalog filters typed GitHub MCP tools and pages discovery.
 Package mcpcatalog filters typed GitHub MCP tools and pages discovery.
github/internal/opbinding
Package opbinding loads immutable generated GitHub REST bindings.
 Package opbinding loads immutable generated GitHub REST bindings.
github/internal/opcatalog
Package opcatalog owns the generated GitHub capability vocabulary.
 Package opcatalog owns the generated GitHub capability vocabulary.
github/internal/operations
Package operations owns generated GitHub operation adapters.
 Package operations owns generated GitHub operation adapters.
github/internal/policy
github/internal/schemaregistry
Package schemaregistry owns closed generated GitHub operation schemas.
 Package schemaregistry owns closed generated GitHub operation schemas.
github/internal/security
github/internal/targetregistry
Package targetregistry owns GitHub target kinds and safe policy fields.
 Package targetregistry owns GitHub target kinds and safe policy fields.
github/internal/upstream
Package upstream owns the pinned GitHub source snapshots used by generators.
 Package upstream owns the pinned GitHub source snapshots used by generators.
huggingface/cmd/hf-broker command
huggingface/internal/approval
Package approval renders Hugging Face-specific operator approval messages.
 Package approval renders Hugging Face-specific operator approval messages.
huggingface/internal/config
Package config loads broker configuration from the environment.
 Package config loads broker configuration from the environment.
huggingface/internal/gitproxy
Package gitproxy contains git smart-HTTP request parsing and append-only push enforcement helpers.
 Package gitproxy contains git smart-HTTP request parsing and append-only push enforcement helpers.
huggingface/internal/hfgrant
Package hfgrant maps Hugging Face request fields onto canonical Brokerkit grants.
 Package hfgrant maps Hugging Face request fields onto canonical Brokerkit grants.
huggingface/internal/hfplan
Package hfplan owns immutable Hugging Face execution plans.
 Package hfplan owns immutable Hugging Face execution plans.
huggingface/internal/httpapi
Package httpapi exposes the broker HTTP surface.
 Package httpapi exposes the broker HTTP surface.
huggingface/internal/hubclient
Package hubclient is the typed, bounded Hugging Face Hub administration client used by hf-broker operation adapters.
 Package hubclient is the typed, bounded Hugging Face Hub administration client used by hf-broker operation adapters.
huggingface/internal/isolation
Package isolation checks whether a local agent identity is isolated from hf-broker's upstream credential on the broker host.
 Package isolation checks whether a local agent identity is isolated from hf-broker's upstream credential on the broker host.
huggingface/internal/jsend
Package jsend builds small JSend response envelopes.
 Package jsend builds small JSend response envelopes.
huggingface/internal/mirror
Package mirror manages commits-only bare mirrors used for append-only ancestry checks.
 Package mirror manages commits-only bare mirrors used for append-only ancestry checks.
huggingface/internal/opbinding
Package opbinding loads the pinned, fixed Hugging Face operation bindings.
 Package opbinding loads the pinned, fixed Hugging Face operation bindings.
huggingface/internal/opcatalog
Package opcatalog owns the complete Hugging Face capability vocabulary.
 Package opcatalog owns the complete Hugging Face capability vocabulary.
huggingface/internal/operations
Package operations owns Hugging Face operation adapters and their registry.
 Package operations owns Hugging Face operation adapters and their registry.
huggingface/internal/policy
Package policy parses and evaluates hf-broker rule-based scope files.
 Package policy parses and evaluates hf-broker rule-based scope files.
huggingface/internal/policypreset
Package policypreset renders provider-owned Hugging Face policy presets.
 Package policypreset renders provider-owned Hugging Face policy presets.
sudo/cmd/sudo-broker command
sudo/cmd/sudo-broker-exec command
sudo/internal/catalog
Package catalog validates and resolves the root-owned sudo command catalog.
 Package catalog validates and resolves the root-owned sudo command catalog.
sudo/internal/executorclient
Package executorclient connects the unprivileged frontend to the Unix helper.
 Package executorclient connects the unprivileged frontend to the Unix helper.
sudo/internal/executorprotocol
Package executorprotocol defines the bounded frontend-to-helper wire protocol.
 Package executorprotocol defines the bounded frontend-to-helper wire protocol.
sudo/internal/executorserver
Package executorserver validates and executes one-shot sudo plans.
 Package executorserver validates and executes one-shot sudo plans.
sudo/internal/hostcheck
Package hostcheck validates privileged filesystem facts.
 Package hostcheck validates privileged filesystem facts.
sudo/internal/plan
Package plan owns immutable sudo execution plans and activation validation.
 Package plan owns immutable sudo execution plans and activation validation.
sudo/internal/presenter
Package presenter renders bounded sudo command approval details.
 Package presenter renders bounded sudo command approval details.
sudo/internal/privexec
Package privexec performs the final no-shell Unix privilege transition.
 Package privexec performs the final no-shell Unix privilege transition.
sudo/internal/routes
Package routes assembles sudo-broker's unprivileged HTTP frontend.
 Package routes assembles sudo-broker's unprivileged HTTP frontend.
sudo/internal/sudopolicy
Package sudopolicy defines sudo-broker's provider-owned policy vocabulary.
 Package sudopolicy defines sudo-broker's provider-owned policy vocabulary.
Package capability defines provider-neutral operation catalog metadata and structural validation.
 Package capability defines provider-neutral operation catalog metadata and structural validation.
Package clientconfig writes per-client broker environment files.
 Package clientconfig writes per-client broker environment files.
Package clienthttp contains shared safety defaults for broker HTTP clients.
 Package clienthttp contains shared safety defaults for broker HTTP clients.
cmd
brokerkit-coverage command
brokerkit-release command
Package conformance provides reusable black-box broker contract tests.
 Package conformance provides reusable black-box broker contract tests.
Package controlplane assembles Brokerkit's shared broker control plane.
 Package controlplane assembles Brokerkit's shared broker control plane.
Package credentialstore persists generated provider credentials in named, broker-owned encrypted slots.
 Package credentialstore persists generated provider credentials in named, broker-owned encrypted slots.
Package decision owns the single BrokerKit decision path used by every transport.
 Package decision owns the single BrokerKit decision path used by every transport.
Package doctor provides secret-safe local broker isolation checks.
 Package doctor provides secret-safe local broker isolation checks.
Package envfile reads the strict environment files generated for broker services.
 Package envfile reads the strict environment files generated for broker services.
Package gitx contains provider-neutral Git smart-HTTP helpers.
 Package gitx contains provider-neutral Git smart-HTTP helpers.
Package grantclient provides provider-neutral temporary-grant HTTP mechanics.
 Package grantclient provides provider-neutral temporary-grant HTTP mechanics.
Package grants stores short-lived broker approval grants.
 Package grants stores short-lived broker approval grants.
Package httpx contains small HTTP safety helpers for broker proxies.
 Package httpx contains small HTTP safety helpers for broker proxies.
Package installer contains the canonical broker-family binary installer.
 Package installer contains the canonical broker-family binary installer.
internal
copyx
Package copyx contains small internal copy helpers.
 Package copyx contains small internal copy helpers.
keyfile
Package keyfile loads or creates private symmetric keys for local stores.
 Package keyfile loads or creates private symmetric keys for local stores.
optional
Package optional contains small helpers for generated optional fields.
 Package optional contains small helpers for generated optional fields.
secretset
Package secretset validates and matches named shared-secret identities.
 Package secretset validates and matches named shared-secret identities.
securefile
Package securefile owns durable writes shared by BrokerKit-private stores.
 Package securefile owns durable writes shared by BrokerKit-private stores.
sortedlookup
Package sortedlookup provides lookup for immutable sorted registries.
 Package sortedlookup provides lookup for immutable sorted registries.
strictjson
Package strictjson provides structural checks missing from encoding/json.
 Package strictjson provides structural checks missing from encoding/json.
validatex
Package validatex contains small validation helpers shared inside brokerkit.
 Package validatex contains small validation helpers shared inside brokerkit.
Package notify defines broker approval notification interfaces.
 Package notify defines broker approval notification interfaces.
telegram
Package telegram implements a reusable Telegram approval notifier.
 Package telegram implements a reusable Telegram approval notifier.
Package operationruntime owns the provider-neutral capability adapter registry and Agent Operations V1 lifecycle orchestration.
 Package operationruntime owns the provider-neutral capability adapter registry and Agent Operations V1 lifecycle orchestration.
Package operatorapi exposes BrokerKit Operator V1 over protected HTTP.
 Package operatorapi exposes BrokerKit Operator V1 over protected HTTP.
Package operatorauth authenticates operator identities independently of broker clients.
 Package operatorauth authenticates operator identities independently of broker clients.
Package operatorclient implements the BrokerKit Operator V1 Source contract.
 Package operatorclient implements the BrokerKit Operator V1 Source contract.
Package operatorfake provides a real in-process operator API for consumer tests.
 Package operatorfake provides a real in-process operator API for consumer tests.
Package operatorinbox projects durable grants into bounded, operator-safe records.
 Package operatorinbox projects durable grants into bounded, operator-safe records.
Package operatorv1 defines the provider-neutral Operator V1 domain contract.
 Package operatorv1 defines the provider-neutral Operator V1 domain contract.
Package operatorv1wire maps Operator V1 domain values to generated wire values.
 Package operatorv1wire maps Operator V1 domain values to generated wire values.
Package plandigest provides content identifiers for immutable broker plans.
 Package plandigest provides content identifiers for immutable broker plans.
Package policy evaluates broker authorization rules.
 Package policy evaluates broker authorization rules.
protocol
agentwire
Package agentwire provides primitives to interact with the openapi HTTP API.
 Package agentwire provides primitives to interact with the openapi HTTP API.
operatorwire
Package operatorwire provides primitives to interact with the openapi HTTP API.
 Package operatorwire provides primitives to interact with the openapi HTTP API.
Package schemautil contains provider-neutral closed-schema helpers.
 Package schemautil contains provider-neutral closed-schema helpers.
Package sealedpayload owns the provider-neutral upload and expiry lifecycle for encrypted, single-use operation inputs.
 Package sealedpayload owns the provider-neutral upload and expiry lifecycle for encrypted, single-use operation inputs.
Package sealedstore stores short-lived encrypted operation payloads outside the broker database.
 Package sealedstore stores short-lived encrypted operation payloads outside the broker database.
Package secretfile reads and renders deterministic named-secret files.
 Package secretfile reads and renders deterministic named-secret files.
Package service renders provider-neutral broker service definitions.
 Package service renders provider-neutral broker service definitions.
Package setup provides reusable broker setup command primitives.
 Package setup provides reusable broker setup command primitives.
Package state owns BrokerKit's local transactional database and process lease.
 Package state owns BrokerKit's local transactional database and process lease.
internal/dbsql
Package store provides small durable local storage helpers.
 Package store provides small durable local storage helpers.
Package streamstore persists bounded, short-lived provider byte streams in private files without loading them into memory or SQLite.
 Package streamstore persists bounded, short-lived provider byte streams in private files without loading them into memory or SQLite.
tooling
coverage
Package coverage runs a consistent Go coverage gate for broker repositories.
 Package coverage runs a consistent Go coverage gate for broker repositories.
release
Package release builds reproducible broker release archives.
 Package release builds reproducible broker release archives.
Package usebudget models finite and unlimited approval use budgets.
 Package usebudget models finite and unlimited approval use budgets.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.