approvals

func New ¶

func New(j *agent.Journal, verifierFor agent.ApproverVerifierFor, opts ...Option) (*Handler, error)

New returns the intake handler over j, the application's own journal: for decisions to be signed as they are written, j's store must be the audit.AuditedStore (or wrap it). verifierFor resolves an approver id to the key enrolled for it, as agent.WithApproverVerifiers does; a decision whose approver has no key, or whose signature does not verify under it, is refused.

WithGatePolicy is required: New returns an error wrapping agent.ErrConfig without it, because the handler counts a gate under the policy the agent is built with. WithAuth is required only with WithPage or WithCORS, which expose a call's arguments to a browser.

package main

import (
	"context"
	"fmt"
	"net/http"

	"github.com/bide-ai/bide/agent"
	"github.com/bide-ai/bide/agent/agenttest"
	"github.com/bide-ai/bide/approvals"
)

func main() {
	journal := agenttest.MemJournal()
	keys := func(id string) (agent.ApproverVerifier, bool) { return nil, false } // the enrolled keys

	policies := map[string]*agent.ApprovalPolicy{
		"charge": {Need: 2, Approvers: []string{"ops", "finance", "risk"}}, // the policy the tool was built with
	}
	h, err := approvals.New(journal, keys,
		approvals.WithGatePolicy(func(tool string) (*agent.ApprovalPolicy, bool) { p, ok := policies[tool]; return p, ok }),
		approvals.OnRecorded(func(ctx context.Context, r approvals.Recorded) {
			if r.Decided {
				// Re-run r.RootRunID now, or leave it to agent.RecoverLoop.
			}
		}),
		approvals.WithAuth(func(req *http.Request, a approvals.Access) error {
			if req.TLS == nil || len(req.TLS.PeerCertificates) == 0 {
				return approvals.ErrUnauthenticated // require a client certificate
			}
			return nil
		}))
	if err != nil {
		fmt.Println(err)
		return
	}
	mux := http.NewServeMux()
	mux.Handle("/approvals/", http.StripPrefix("/approvals", h))
	fmt.Println("mounted")
}

Output:
mounted

func OnRecorded ¶

func OnRecorded(fn func(context.Context, Recorded)) Option

OnRecorded sets the function called, in a goroutine of its own and with a context that outlives the request, once for each decision this handler wrote (never for a replay or a refusal). It is where the application re-runs the run, or schedules it, by its own policy:

if r.Decided { _, err := agent.Run(ctx, r.RootRunID, ...) }

It is an accelerator, not the guarantee: a run waiting on a decision is also picked up by agent.RecoverLoop, and the hook is dropped, with a report to WithOnError, when WithMaxInFlight hooks are already running. Wait waits for the running hooks.

func WithAuth ¶

func WithAuth(fn func(*http.Request, Access) error) Option

WithAuth sets a hook that runs for every request, after the rate limit and before the journal is read or written, with what the request asks for. A POST /decisions calls it twice, and Access.Phase says which call it is: PhaseIdentity first, from the headers and the connection, before the body is read (RunID, ToolUseID and Approver empty: it must only authenticate), so a client that fails it is refused without costing a stalled read; then PhaseRequest with the decision's run, call and approver once the body is parsed, where a hook that ties an approver to a client certificate enforces the binding. The hook must be idempotent: both calls are made for one request. Return nil to allow it, ErrUnauthenticated for a request with no valid credentials (401), or ErrForbidden, or any other error, to refuse it (403). It is where a deployment checks a client certificate (r.TLS.PeerCertificates) or an identity, and ties an approver id to it (Access.Approver). The signature is the authorization of a decision; this hook decides who may reach the endpoint at all, and who may read a call's arguments, which GET /pending shows to any caller it allows.

func WithCORS ¶

func WithCORS(origin string) Option

WithCORS lets a page hosted at origin (an exact origin such as "https://approve.example.com", never "*") call the intake from a browser: it answers the CORS preflight (OPTIONS) before any authentication, since a preflight carries no credentials and a browser can never reach an endpoint that refuses it, and adds the Access-Control headers to responses to that origin. It requires WithAuth. Credentials are not allowed cross-origin unless WithCORSCredentials says so; a deployment that authenticates with a cookie or a client certificate from another origin sets it, and the page's config.json asks for credentials "include". A deployment that needs neither serves the page from the intake's origin.

func WithCORSCredentials ¶

func WithCORSCredentials() Option

WithCORSCredentials lets the page send credentials cross-origin (fetch's credentials mode "include", which config.json asks for): cookies, HTTP authentication and, for mutual TLS, the browser's client certificate, which a browser does not present on a cross-origin request made with credentials omitted. It adds Access-Control-Allow-Credentials, which a browser accepts only with the exact origin WithCORS names. It requires WithCORS.

func WithClientKey ¶

func WithClientKey(fn func(*http.Request) string) Option

WithClientKey names the client a request is limited as (and the client whose concurrent body reads are capped). By default it is the host of r.RemoteAddr, an IPv6 address standing for its /64 (the unit an operator assigns to one host or site) and an IPv4-mapped one for the IPv4 address; behind a reverse proxy or load balancer that is the proxy's address, so every client shares one bucket: set it there, to a function that reads the address the proxy vouches for (and only that header, which the proxy must overwrite, never pass through from the client).

func WithClock ¶

func WithClock(now func() time.Time) Option

WithClock sets the clock the rate limits run on and the decision's recorded_at is read from.

func WithGatePolicy ¶

func WithGatePolicy(fn func(tool string) (*agent.ApprovalPolicy, bool)) Option

WithGatePolicy gives the handler each gated tool's live approval policy, as the application's agent is built with it (the ToolSpec's Approval). It is required: New returns an error wrapping agent.ErrConfig without it. A gate's policy is also in the pause note, which the run writes once when it first pauses, so a redeploy that changes the policy afterwards (turning on ExcludePrincipal, say) is enforced by the gate when the run resumes but is not in the note. If the gate's recorded tally passed under the old policy and the call has not run, the gate asks again; a handler that read the old policy from the note would show the gate as decided and refuse the new approvals (not_waiting), and the run would wait for ever. So a gate on a tool fn knows is counted under the live policy, by agent.EvaluateGate, the function the agent's own gate evaluates with, so the two cannot disagree: the policy's shape (a one-decision gate is not served), its validity and keys (a gate the gate would refuse is refused here, state "error"), separation of duties, a recorded tally it supersedes, and the count. fn returns ok false for a tool it does not know, and the pause note is then the fallback; ok true with a nil policy says the tool has no gate now. fn is called for every request that reads a gate, so it should be a lookup:

approvals.WithGatePolicy(func(tool string) (*agent.ApprovalPolicy, bool) {
    p, ok := policies[tool] // the policies the tools were built with agent.WithApproval
    return p, ok
})

func WithGlobalRateLimit ¶

func WithGlobalRateLimit(rate float64, burst int) Option

WithGlobalRateLimit sets the request rate and burst over all clients together; DefaultGlobalRate and DefaultGlobalBurst by default. A rate of 0 turns it off.

func WithMaxBodyBytes ¶

func WithMaxBodyBytes(n int64) Option

WithMaxBodyBytes bounds a request body (DefaultMaxBodyBytes by default). A larger body is 413.

func WithMaxClients ¶

func WithMaxClients(n int) Option

WithMaxClients bounds how many clients' buckets are kept (DefaultMaxClients). Past it, new clients share one bucket, so a flood of sources is limited as one.

func WithMaxInFlight ¶

func WithMaxInFlight(n int) Option

WithMaxInFlight bounds the requests working on the journal at once, and the OnRecorded hooks running at once (DefaultMaxInFlight). A request past it is answered 503 with Retry-After.

func WithMaxReaders ¶

func WithMaxReaders(total, perClient int) Option

WithMaxReaders bounds the request bodies being read at once, overall and for one client (DefaultMaxReaders, DefaultMaxReadersPerClient). A body is read before the request takes a slot for work on the journal, in a pool of its own, so a client that stalls while sending cannot starve requests that are working; past either bound a request is refused (503 overall, 429 for a client over its own) with Retry-After. Authorization has run by then (see WithAuth).

func WithOnError ¶

func WithOnError(fn func(error)) Option

WithOnError sets the function the handler tells of what it does not show a caller: a store error, a refused hook. It may be called from several goroutines.

func WithPage ¶

func WithPage() Option

WithPage makes the handler serve the approve page under /page/: an approver opens <mount>/page/#run=<id>&call=<id> and signs in the browser. It requires WithAuth (New returns an error without it): the page reads a call's arguments through GET /pending, so the endpoint must know who is asking, and the same hook authorizes the page's own files.

The page is then served by the application, so the application can change what it does and can serve a script that signs anything the approver's key will sign; the page says so on its face. It is for development and for low-assurance use. For anything that matters, host PageFiles on an origin of the approver's organization (a dedicated one: IndexedDB and the key in it are scoped to the origin), pin the bundle by PageSHA256, and allow it with WithCORS. See docs/design/approve-page.md.

func WithRateLimit ¶

func WithRateLimit(rate float64, burst int) Option

WithRateLimit sets the per-client request rate (a second) and burst; DefaultRate and DefaultBurst by default. A rate of 0 turns the per-client limit off.

func WithReadTimeout ¶

func WithReadTimeout(d time.Duration) Option

WithReadTimeout bounds how long a POST /decisions may take to send its body (DefaultReadTimeout). The body is read in the read pool (WithMaxReaders), so a stalled client costs one reader for at most this long and no slot for work on the journal. It does not replace http.Server.ReadHeaderTimeout, which bounds the headers before the handler runs: set both.