Skip to content

Package notify ​

Go module github.com/bide-ai/bide; all packages.

github.com/bide-ai/bide/notify · pkg.go.dev · Stability: core

Package notify ships bide's webhook notifier: a signed HTTPS POST of a structured notification, and the receiver-side Verify that checks one.

Constants

  • const HeaderDelivery = "Bide-Delivery", const HeaderTimestamp = "Bide-Timestamp", const HeaderSignature = "Bide-Signature": Header names of a webhook request.
  • const DefaultTimeout = 10 * time.Second, const MaxRequests = 3: Defaults of a Webhook.
  • const DefaultTolerance = 5 * time.Minute: DefaultTolerance is how far a request's timestamp may be from the receiver's clock before Verify rejects it, when the caller passes a tolerance of zero.
  • const Schema = "bide.notification.v1": Schema is the value of the payload's "schema" field.

Variables

  • var ErrNoSignature, var ErrBadTimestamp, var ErrStale, var ErrBadSignature, var ErrNoSecrets, var ErrShortSecret, var ErrBodyTooLarge, var ErrDeliveryID: Verification errors.
  • var ErrorText: ErrorText allows the typed error's text ("error") in the payload.

Functions

  • func CheckSecret(secret string) error: CheckSecret reports whether this process can use secret as a webhook signing secret: it returns ErrShortSecret for a non-empty secret shorter than 14 bytes under strict FIPS enforcement (GODEBUG=fips140=only), and nil otherwise.
  • func SPKIHash(c *x509.Certificate) string: SPKIHash returns the hex SHA-256 of a certificate's SubjectPublicKeyInfo: the value WithServerPin takes, and the value recorded as the client certificate in a delivery's audit record.
  • func Sign(secrets []string, ts int64, body []byte) string: Sign returns the Bide-Signature header value for body sent at ts: one "v1=<hex>" entry per secret, space separated, where each is HMAC-SHA256(secret, ts + "." + body).
  • func Verify(r *http.Request, secrets []string, tolerance time.Duration) error: Verify checks a request from a bide webhook in one call, for use in a receiver.
  • func VerifyBody(timestamp, signature string, body []byte, secrets []string, tolerance time.Duration, now time.Time) error: VerifyBody is Verify over parts the caller already holds, such as a stored body and its headers when checking a delivery later as evidence.

type Abort ​

go
type Abort struct {
	Reason string `json:"reason"`
}

Abort is the detail of a run_aborted event; Reason is a code from a closed set, not text.

type Approval ​

go
type Approval struct {
	ToolUseID string   `json:"tool_use_id"`
	Tool      string   `json:"tool"`
	Policy    Policy   `json:"policy"`
	Approvers []string `json:"approvers"`
	Approved  int      `json:"approved"`

	Excluded []string `json:"excluded,omitempty"`

	Reask string `json:"reask,omitempty"`

	Why  []agent.GateReason `json:"why,omitempty"`
	Args json.RawMessage    `json:"args,omitempty"`
}

Approval is the detail of an approval_pending event: who may decide and how many must.

type Clears ​

go
type Clears struct {
	ID   string `json:"id"`
	Key  string `json:"key"`
	Kind string `json:"kind"`
}

Clears is the detail of a resolved notification, the all-clear: the event that stopped being current.

type Escalates ​

go
type Escalates struct {
	ID    string `json:"id"`
	Key   string `json:"key"`
	Kind  string `json:"kind"`
	Level int    `json:"level"`
}

Escalates is the detail of an escalated notification.

type Failing ​

go
type Failing struct {
	Cause string `json:"cause"`
}

Failing is the detail of a recovery_failing event; Cause is a class, not text.

type Field ​

go
type Field struct {
	// contains filtered or unexported fields
}

A Field is a payload field that is left out unless named in WithFields.

Constructors and functions

  • func Args(tools ...string) Field: Args allows the arguments of an approval-pending call ("approval.args") for the named tools only.

type Halt ​

go
type Halt struct {
	Cause       string     `json:"cause"`
	AttemptedAt *time.Time `json:"attempted_at"`
}

Halt is the detail of an outcome_unknown event.

type Option ​

go
type Option func(*Webhook) error

An Option configures NewWebhook.

Constructors and functions

  • func WithClientCert(certFile, keyFile string) Option: WithClientCert presents a client certificate for mutual TLS, read from PEM files.
  • func WithClientCertPEM(certPEM, keyPEM []byte) Option: WithClientCertPEM is WithClientCert for a pair held in memory, such as one read from the environment.
  • func WithFields(fs ...Field) Option: WithFields allows payload fields that are left out by default.
  • func WithOnError(f func(error)) Option: WithOnError sets where non-fatal problems are reported, such as a client certificate that failed to reload (the last good pair stays in use).
  • func WithProxy(f func(*http.Request) (*url.URL, error)) Option: WithProxy sets how the webhook reaches the receiver through a proxy (nil means directly).
  • func WithRequestsPerCall(n int) Option: WithRequestsPerCall sets how many requests one Notify call may make, with backoff of 1 s then 2 s between them (default 1, at most MaxRequests).
  • func WithSecrets(current, previous string) Option: WithSecrets sets the signing secrets.
  • func WithServerCA(file string) Option: WithServerCA verifies the receiver against the CA certificates in a PEM file instead of the system roots.
  • func WithServerCAPEM(pem []byte) Option: WithServerCAPEM is WithServerCA for a bundle held in memory.
  • func WithServerPin(pins ...string) Option: WithServerPin pins the receiver's key: after normal certificate verification, the handshake fails unless a certificate in the verified chain has a SubjectPublicKeyInfo whose SHA-256 is one of the pins (64 hex characters or base64; see SPKIHash).
  • func WithTimeout(d time.Duration) Option: WithTimeout sets the timeout of each request (default 10 seconds).
  • func WithViewDB(path string) Option: WithViewDB names the SQLite journal file the deployment's runs are in, so the payload's view.command is a command that runs: bide view -db <path> -run <id>.
  • func WithViewURL(base string) Option: WithViewURL sets the base URL of the deployment's run viewer; the payload's view.url is then base + "/" + run ID, escaped.

type Payload ​

go
type Payload struct {
	Schema     string     `json:"schema"`
	ID         string     `json:"id"`
	Key        string     `json:"key"`
	Kind       string     `json:"kind"`
	RunID      string     `json:"run_id"`
	EventAt    *time.Time `json:"event_at"`
	ObservedAt *time.Time `json:"observed_at"`
	DeadlineAt *time.Time `json:"deadline_at"`
	Attempt    int        `json:"attempt"`
	Summary    string     `json:"summary"`
	Step       *Step      `json:"step"`
	Halt       *Halt      `json:"halt"`
	Principal  *Principal `json:"principal"`
	Approval   *Approval  `json:"approval"`
	Abort      *Abort     `json:"abort"`
	Failing    *Failing   `json:"failing"`

	Stop *Stop `json:"stop"`

	Clears *Clears `json:"clears"`

	Escalates *Escalates `json:"escalates"`

	Receiver string `json:"receiver,omitempty"`
	Reason   string `json:"reason,omitempty"`
	View     View   `json:"view"`

	Error string `json:"error,omitempty"`
}

Payload is the JSON body of a webhook request, schema bide.notification.v1.

type PermanentError ​

go
type PermanentError struct{ Status int }

PermanentError is returned for a response that retrying inside the round cannot fix: any 4xx other than 429, or a redirect.

Methods

  • func (e *PermanentError) Error() string: Error names the status only: no URL, no body.
  • func (e *PermanentError) Unwrap() error: Unwrap makes errors.Is(err, agent.ErrNotifyPermanent) true.

type Policy ​

go
type Policy struct {
	Need int `json:"need"`
	Of   int `json:"of"`
}

Policy is the gate's k of n.

type Principal ​

go
type Principal struct {
	OnBehalfOf   string `json:"on_behalf_of"`
	AuthorityRef string `json:"authority_ref"`
}

Principal is the party the run acts for.

type ProbeResult ​

go
type ProbeResult struct {
	Status int

	TLS bool

	Handshake     bool
	HandshakeErr  error
	HandshakeTime time.Duration
	TLSVersion    string

	Auth *agent.NotifyAuth

	Requests int
	Elapsed  time.Duration
}

ProbeResult is what one delivery looked like from the sender's side, for a tool that tests a receiver (bide notify test).

type Step ​

go
type Step struct {
	OpKind string `json:"op_kind"`
	OpID   string `json:"op_id"`
	Tool   string `json:"tool,omitempty"`
}

Step names the operation an event is about.

type Stop ​

go
type Stop struct {
	ID           string   `json:"id"`
	Scope        string   `json:"scope"`
	Name         string   `json:"name,omitempty"`
	Reason       string   `json:"reason"`
	By           string   `json:"by"`
	Host         string   `json:"host,omitempty"`
	Mode         string   `json:"mode"`
	Signed       bool     `json:"signed"`
	Compensation string   `json:"compensation"`
	LiftedBy     []string `json:"lifted_by,omitempty"`
}

Stop is the detail of a stop_set or stop_lifted event.

type View ​

go
type View struct {
	Command string  `json:"command"`
	URL     *string `json:"url"`
}

View points at where to look.

type Webhook ​

go
type Webhook struct {
	// contains filtered or unexported fields
}

A Webhook delivers notifications as signed HTTPS POSTs.

Constructors and functions

  • func NewWebhook(rawURL string, opts ...Option) (*Webhook, error): NewWebhook returns a Webhook that posts to rawURL.

Methods

  • func (w *Webhook) Notify(ctx context.Context, n agent.Notification) error: Notify delivers n as one signed POST, retrying inside the round (see MaxRequests).
  • func (w *Webhook) Probe(ctx context.Context, n agent.Notification) (ProbeResult, error): Probe delivers n exactly as Notify does (the same payload, signature, TLS options and request rules) and reports how the delivery went, without the audit acknowledgement Notify makes.

Apache-2.0 licensed.