brokerkit

package module
v0.1.0 Latest Latest
Warning

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

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

README

brokerkit

brokerkit is a Go library for building broker-style access-control services. It provides shared primitives for projects where an untrusted client receives a broker secret while the service keeps the real credential or privilege boundary server-side.

The first intended users are hf-broker, gh-broker, and sudo-broker. brokerkit is the long-term shared base for those projects. Each broker should cut over to brokerkit for shared auth, policy, grants, approval workflow, audit, notification, Telegram approval transport, common storage/config helpers, and generic Git parsing helpers instead of maintaining a parallel compatibility runtime.

brokerkit should stay small: it is not a full broker framework, and it should 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 should own Unix user switching, command catalogs, TTY sessions, and sudo/systemd/launchd integration.

The canonical ownership boundary is in docs/OWNERSHIP.md. The shared install, setup, policy, grant, approval, audit, doctor, and release contract is in docs/UNIFIED_BROKER_CONTRACT.md.

Packages

Implemented package candidates 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
  • 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 broker repository 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 web applications such as mlclaw
  • gitx: generic Git smart-HTTP parsing helpers, if shared cleanly by hf-broker and gh-broker
  • store: atomic file storage and lock helpers, if needed by grants/audit

Provider-specific execution code does not belong in brokerkit.

The packages above have initial Go implementations.

Status

This repository now contains the shared Go packages plus the design documents that define the cutover boundary. 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 live cross-repository implementation order and remaining work are tracked in docs/CUTOVER_STATUS.md. The operator backend and trusted web-host integration contract is documented in docs/OPERATOR_INBOX.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 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 clientconfig writes per-client broker environment files.
 Package clientconfig writes per-client broker environment files.
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 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 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.
secretset
Package secretset validates and matches named shared-secret identities.
 Package secretset validates and matches named shared-secret identities.
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 operatorapi exposes the Brokerkit operator inbox over protected HTTP.
 Package operatorapi exposes the Brokerkit operator inbox over protected HTTP.
Package operatorauth authenticates operator identities independently of broker clients.
 Package operatorauth authenticates operator identities independently of broker clients.
Package operatorclient is a small Go client for the Brokerkit operator API.
 Package operatorclient is a small Go client for the Brokerkit operator API.
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 policy evaluates broker authorization rules.
 Package policy evaluates broker authorization rules.
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 store provides small durable local storage helpers.
 Package store provides small durable local storage helpers.
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.

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.