approval

package
v1.164.0 Latest Latest
Warning

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

Go to latest
Published: Nov 18, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package approval is the Approvals queue (#2437): a request for a decision, made by the person who needs it and decided by an administrator. This release carries one subject, a managed script's version, for one purpose: serving a form to callers with no session (#2494). A request names the version by number and fixes it by the sha256 of its source, so what is approved is exactly what the approver was shown, and it says what changed since the version last approved for the same purpose.

Administrators decide. An administrator may decide their own request, and the record says so; nobody else may decide one, their own included.

Index

Constants

View Source
const (
	SubjectScriptVersion = "script_version"
	SubjectSiteRelease   = "site_release"
	// SubjectSiteEnvironment is one environment of a site, by SiteID and
	// Target (#2604).
	SubjectSiteEnvironment = "site_environment"
	PurposeFormPublic      = "form_public"
	PurposeSitePromote     = "site_promote"
	// PurposeSitePublic makes a site environment that requires approval
	// public; SourceSHA256 is the access it was asked against.
	PurposeSitePublic = "site_public"
	// PurposeSiteRedirect redirects a site environment that requires
	// approval to another website (#2632); Target is the environment and
	// SourceSHA256 the redirect asked for (its target and path rule).
	PurposeSiteRedirect = "site_redirect"
	// SubjectCall is a held tool call (#2437): approved, it is an allowance
	// of calls of one operation, for one person, on one connection, until a
	// deadline.
	SubjectCall = "call"
	// PurposeCallAllowance is a call request's purpose.
	PurposeCallAllowance = "call_allowance"
	// PurposeCallHandler approves a script version to run as a tool-call
	// handler (#2436): a policy, transform or watch runs the highest version
	// approved for it, with the roles of the administrator who approved it.
	PurposeCallHandler = "call_handler"
)

The subject kinds and purposes a request has.

View Source
const (
	KindCall           = "call"
	KindHandlerVersion = "handler_version"
	KindForm           = "form"
	KindSite           = "site"
)

The kinds a list filters requests by.

View Source
const (
	StatusPending   = "pending"
	StatusApproved  = "approved"
	StatusDenied    = "denied"
	StatusWithdrawn = "withdrawn"
)

The statuses a request moves through. A request is decided once.

View Source
const (
	DecisionApprove = "approve"
	DecisionDeny    = "deny"
)

The decisions an administrator makes.

View Source
const (
	// MaxCalls is the most calls one allowance holds.
	MaxCalls = 10000
	// DefaultAllowance is how long an approved allowance lasts when the
	// approver sets no deadline.
	DefaultAllowance = 24 * time.Hour
	// MaxAllowance is the furthest deadline an approver may set.
	MaxAllowance = 90 * 24 * time.Hour
	// Administrators is how a policy names every administrator as its
	// approver.
	Administrators = "administrators"
)

Bounds on a call request's allowance.

View Source
const MaxReason = 2000

MaxReason bounds the reason a requester gives and the comment a decision carries.

Variables

View Source
var (
	ErrNotFound   = errors.New("approval: no such request")
	ErrNotAllowed = errors.New("approval: not allowed")
	ErrDecided    = errors.New("approval: the request was already decided")
	ErrPending    = errors.New("approval: a request for this version is already waiting")
)

Errors a caller reads by identity.

Functions

func NewID

func NewID() string

NewID is a request id.

func SourceHash

func SourceHash(source string) string

SourceHash is the sha256 a version's source is fixed by.

Types

type Actor

type Actor struct {
	Email   string
	Persona string
	Admin   bool
	// Roles are the actor's roles: what a handler version an administrator
	// approves runs with.
	Roles []string
	// Agent is true when an agent acts for the person (an MCP tool call, or
	// the platform's own API reached from one), false in the portal.
	Agent bool
}

Actor is who is asking.

type Allowance added in v1.161.0

type Allowance struct {
	Calls int
	Until *time.Time
}

Allowance is what an approver grants: a number of calls until a deadline. Zero values take what was asked and DefaultAllowance.

type AllowanceStore added in v1.161.0

type AllowanceStore interface {
	// Spend uses one call of the oldest approved allowance requester holds
	// for operation on connection that has calls left and has not passed
	// its deadline, returning its id; ok is false when none does.
	Spend(ctx context.Context, requester, connection, operation string) (id string, ok bool, err error)
}

AllowanceStore spends approved allowances (PostgresStore).

type CallRequest added in v1.161.0

type CallRequest struct {
	Tool       string
	Connection string
	Operation  string
	// Arguments are the call's arguments as the caller sent them, before
	// any stored secret is filled.
	Arguments map[string]any
	Rendering string
	Handlers  []HandlerAsk
	Approvers []string
	Calls     int
	Reason    string
}

CallRequest is a held call to file (#2437): what the platform read of it and what its policies asked.

type CallSubject added in v1.161.0

type CallSubject struct {
	CallTool       string         `json:"tool,omitempty" example:"api_invoke_endpoint"`
	CallConnection string         `json:"connection,omitempty" example:"billing-api"`
	CallOperation  string         `json:"operation,omitempty" example:"addSubscribers"`
	CallArguments  map[string]any `json:"arguments,omitempty"`
	// Rendering is the platform's own reading of the call, which the
	// approver reads, never only a summary someone wrote.
	Rendering string `json:"rendering,omitempty"`
	// Handlers are the policies that held the call, with what each said.
	Handlers []HandlerAsk `json:"handlers,omitempty"`
	// Approvers are the people or personas the policies named; empty is an
	// administrator.
	Approvers     []string   `json:"approvers,omitempty"`
	CallsAsked    int        `json:"calls_asked,omitempty"`
	CallsApproved int        `json:"calls_approved,omitempty"`
	CallsUsed     int        `json:"calls_used,omitempty"`
	Until         *time.Time `json:"until,omitempty"`
}

CallSubject is a call request's subject (#2437): the call as the caller sent it, frozen when filed, what the platform made of it, the handlers that held it, who may decide it, and the allowance.

type Changes

type Changes struct {
	// ApprovedVersion is the version approved before, 0 for none.
	ApprovedVersion int `json:"approved_version"`
	// Diff is the unified diff of the source from that version, empty for a
	// first request; Truncated says it was cut at the bound.
	Diff      string `json:"diff,omitempty"`
	Truncated bool   `json:"truncated,omitempty"`
	// Added and Removed count the diff's changed lines.
	Added   int `json:"added"`
	Removed int `json:"removed"`
}

Changes is what changed since the version last approved for the same purpose: none approved before is a first request.

type Decision

type Decision struct {
	Status       string
	By           string
	Comment      string
	SelfApproved bool
	At           time.Time
	// Roles are the approver's roles, recorded for a handler version.
	Roles []string
	// CallsApproved and Until are an allowance's count and deadline.
	CallsApproved int
	Until         *time.Time
}

Decision is what an administrator decided about a request.

type Filter

type Filter struct {
	// Status is one status, empty for every one.
	Status string
	// Requester is one requester's requests, empty for everyone's.
	Requester string
	// ScriptID is one script's requests, empty for every script's.
	ScriptID string
	// SiteReleaseID is one site release's requests, empty for every one's.
	SiteReleaseID string
	// SiteID is one site's environment requests, empty for every site's.
	SiteID string
	// Approver and ApproverPersona widen a requester's listing to the call
	// requests whose policies name them, by address or persona.
	Approver        string
	ApproverPersona string
	// Kind is one kind of request (call, handler_version, form, site),
	// empty for every kind; Purpose one purpose.
	Kind    string
	Purpose string
	Limit   int
}

Filter narrows a listing.

type HandlerAsk added in v1.161.0

type HandlerAsk struct {
	ID      string `json:"id"`
	Script  string `json:"script"`
	Summary string `json:"summary,omitempty"`
}

HandlerAsk is one policy that held a call, and what it said.

type HeldCall added in v1.161.0

type HeldCall struct {
	User, Persona, Tool string
	Arguments           map[string]any
	Calls               int
	Reason              string
}

HeldCall is a call a person was told is held, as manage_approval submit names it: who made it, under which persona, the tool and its arguments as the call was made, how many calls to ask for and why.

type Notifier

type Notifier interface {
	Requested(ctx context.Context, r *Request, approvers []string)
	Decided(ctx context.Context, r *Request)
}

Notifier tells approvers a request is waiting and a requester how theirs was decided. Its failures are its own: a request stands whether or not the mail went out.

type PostgresStore

type PostgresStore struct {
	// contains filtered or unexported fields
}

PostgresStore keeps requests in approval_requests.

func NewPostgresStore

func NewPostgresStore(db *sql.DB) *PostgresStore

NewPostgresStore builds the store over db.

func (*PostgresStore) Decide

func (p *PostgresStore) Decide(ctx context.Context, id string, d Decision) (*Request, error)

Decide records a pending request's decision. A call request's frozen arguments are deleted with it (#2437): the approver read them to decide, the allowance is spent by connection and operation, and the platform's rendering stays as the record of what was asked.

func (*PostgresStore) EnvironmentApproved added in v1.158.0

func (p *PostgresStore) EnvironmentApproved(ctx context.Context, siteID, target, stamp string) (bool, error)

EnvironmentApproved reports whether making a site environment public is approved for the access stamp the approver was shown.

func (*PostgresStore) Get

func (p *PostgresStore) Get(ctx context.Context, id string) (*Request, error)

Get reads one request.

func (*PostgresStore) Insert

func (p *PostgresStore) Insert(ctx context.Context, r *Request) error

Insert stores a new pending request.

func (*PostgresStore) LatestApproved

func (p *PostgresStore) LatestApproved(ctx context.Context, scriptID, purpose string) (*Request, error)

LatestApproved is the highest version approved for a script and purpose.

func (*PostgresStore) List

func (p *PostgresStore) List(ctx context.Context, f Filter) ([]Request, error)

List reads requests newest first.

func (*PostgresStore) PendingRollup added in v1.161.0

func (p *PostgresStore) PendingRollup(ctx context.Context, staleBefore time.Time) (QueueRollup, error)

PendingRollup is the approvals queue's rollup (reviewalert.ApprovalSource), staleBefore deciding which requests are stale.

func (*PostgresStore) ReleaseApproved added in v1.155.0

func (p *PostgresStore) ReleaseApproved(ctx context.Context, releaseID, target, digest string) (bool, error)

ReleaseApproved reports whether a site release is approved for a target at the digest the approver was shown.

func (*PostgresStore) Spend added in v1.161.0

func (p *PostgresStore) Spend(ctx context.Context, requester, connection, operation string) (id string, ok bool, err error)

Spend uses one call of an approved allowance.

type QueueRollup added in v1.161.0

type QueueRollup struct {
	Pending, Stale int
	Oldest         *time.Time
}

QueueRollup is the approvals queue as its staleness alert reads it: every pending request, those filed before a time, and when the oldest was filed.

type RefusedError

type RefusedError struct{ Msg string }

RefusedError is a request refused for a reason the caller can act on.

func (*RefusedError) Error

func (e *RefusedError) Error() string

type Request

type Request struct {
	ID               string  `json:"id" example:"apr_0f3c9d2e"`
	SubjectKind      string  `json:"subject_kind" example:"script_version"`
	Purpose          string  `json:"purpose" example:"form_public"`
	ScriptID         string  `json:"script_id"`
	ScriptName       string  `json:"script_name,omitempty" example:"order-intake"`
	Version          int     `json:"version" example:"2"`
	SourceSHA256     string  `json:"source_sha256"`
	RequesterEmail   string  `json:"requester_email" example:"jane@example.com"`
	RequesterPersona string  `json:"requester_persona,omitempty"`
	Reason           string  `json:"reason,omitempty"`
	Changes          Changes `json:"changes"`
	// SiteReleaseID and Target name a site release a promotion waits on and
	// the environment it would serve (#2518); SourceSHA256 is then the
	// release's manifest digest and Version its number.
	SiteReleaseID string `json:"site_release_id,omitempty"`
	Target        string `json:"target,omitempty" example:"prod"`
	// SiteID is the site an environment request is about (#2604).
	SiteID string `json:"site_id,omitempty"`
	// SiteName is the site the release or environment belongs to.
	SiteName        string     `json:"site_name,omitempty" example:"marketing"`
	Status          string     `json:"status" example:"pending"`
	DecidedBy       string     `json:"decided_by,omitempty"`
	DecidedAt       *time.Time `json:"decided_at,omitempty"`
	DecisionComment string     `json:"decision_comment,omitempty"`
	SelfApproved    bool       `json:"self_approved"`
	CreatedAt       time.Time  `json:"created_at"`
	// Kind is what the request is about: call, handler_version, form or
	// site.
	Kind string `json:"kind"`
	// DecidedRoles are the roles of the administrator who approved a
	// handler version, which the handler runs with. They are never shown.
	DecidedRoles []string `json:"-"`
	CallSubject
}

Request is one request for a decision.

type Ruling added in v1.161.0

type Ruling struct {
	Decision, Comment string
	Allowance         Allowance
}

Ruling is one decision on a request: approve or deny, a comment for the requester, and on a call request what an approval grants.

type RunAs added in v1.161.0

type RunAs struct {
	Version  int
	Approver string
	Roles    []string
	// SelfApproved says the approver saved or bound it themselves.
	SelfApproved bool
}

RunAs is what a script's tool-call handlers run (#2436): the highest version approved for call_handler, and the administrator who approved it, whose roles it runs with.

type Scripts

type Scripts interface {
	GetByID(ctx context.Context, id string) (*script.Script, error)
	GetByName(ctx context.Context, ownerEmail, name string) (*script.Script, error)
	GetVersion(ctx context.Context, scriptID string, version int) (*script.Version, error)
}

Scripts reads the scripts and versions a request names.

type Service

type Service struct {
	Store   Store
	Scripts Scripts
	// IsForm reports whether a version's source defines a form; a
	// form_public request names a form's version.
	IsForm func(source string) bool
	// Approvers lists the administrators' addresses; nil notifies nobody.
	Approvers func(ctx context.Context) []string
	// Notifier sends the two notices; nil sends none.
	Notifier Notifier
	// Now is the clock; nil is time.Now.
	Now func() time.Time
	// Allowances spends approved call allowances; nil spends none.
	Allowances AllowanceStore
}

Service is the queue's operations.

func (*Service) ApproveForHandlers added in v1.161.0

func (s *Service) ApproveForHandlers(ctx context.Context, actor Actor, sc *script.Script, version int) error

ApproveForHandlers records an administrator's approval of a version of sc for its tool-call handlers (version 0 is the latest), with their roles, marked self-approved: an administrator saving or binding a handler's script approves what they saved or bound. A version already approved, or older than one approved, records nothing.

func (*Service) Approved

func (s *Service) Approved(ctx context.Context, scriptID, purpose string) int

Approved is the version approved for a script and purpose, 0 for none. A failure to read is logged and reads as none, which serves nothing publicly.

func (*Service) Decide

func (s *Service) Decide(ctx context.Context, actor Actor, id, decision, comment string) (*Request, error)

Decide records an administrator's decision. A non-administrator is refused whatever the request, their own included; an administrator deciding their own request is recorded as self-approved.

func (*Service) DecideAllowance added in v1.161.0

func (s *Service) DecideAllowance(ctx context.Context, actor Actor, id string, r Ruling) (*Request, error)

DecideAllowance is Decide with what an approval of a call request grants (#2437): a call request is decided by the approvers its policies named or an administrator, never by its requester unless an administrator; every other request by an administrator.

func (*Service) EnvironmentApproved added in v1.158.0

func (s *Service) EnvironmentApproved(ctx context.Context, siteID, target, stamp string) bool

EnvironmentApproved reports whether making a site environment public is approved for the stamp. A failure to read is logged and reads as not approved, which makes nothing public.

func (*Service) Get

func (s *Service) Get(ctx context.Context, actor Actor, id string) (*Request, error)

Get is one request actor may read.

func (*Service) HandlerRunAs added in v1.161.0

func (s *Service) HandlerRunAs(ctx context.Context, scriptID string) (RunAs, bool)

HandlerRunAs is what sc's tool-call handlers run; ok is false when no version is approved, and then nothing runs. A failure to read is logged and reads as none.

func (*Service) HandlerVersionSaved added in v1.161.0

func (s *Service) HandlerVersionSaved(ctx context.Context, actor Actor, sc *script.Script, version int) error

HandlerVersionSaved is what a save of a script holding tool-call handlers does: an administrator's save approves the version, anyone else's files a request an administrator decides, and the approved version keeps running meanwhile.

func (*Service) List

func (s *Service) List(ctx context.Context, actor Actor, f Filter) ([]Request, error)

List is the requests actor may read: an administrator's every one, anyone else's their own.

func (*Service) PendingHandlerVersion added in v1.161.0

func (s *Service) PendingHandlerVersion(ctx context.Context, scriptID string) int

PendingHandlerVersion is the newest version of a script waiting for an administrator's approval for handlers, 0 for none.

func (*Service) RecordReleaseSelfApproval added in v1.155.0

func (s *Service) RecordReleaseSelfApproval(ctx context.Context, actor Actor, in SubmitRelease) error

RecordReleaseSelfApproval records an administrator's approval of a release they promote themselves, and the record says it was self-approved.

func (*Service) RecordSelfApproval

func (s *Service) RecordSelfApproval(ctx context.Context, actor Actor, sc *script.Script, version int) error

RecordSelfApproval records an administrator's approval of a version they serve publicly without a request: an administrator binding a form public approves the version served, and the record says it was self-approved. A version already approved records nothing.

func (*Service) ReleaseApproved added in v1.155.0

func (s *Service) ReleaseApproved(ctx context.Context, releaseID, target, digest string) bool

ReleaseApproved reports whether a release is approved for a target at the digest. A failure to read is logged and reads as not approved, which promotes nothing.

func (*Service) ResolveScript

func (s *Service) ResolveScript(ctx context.Context, actor Actor, ref string) (*script.Script, error)

ResolveScript reads the script a request names: by id, or by the name of one of the actor's own scripts.

func (*Service) SpendAllowance added in v1.161.0

func (s *Service) SpendAllowance(ctx context.Context, requester, connection, operation string) (string, bool)

SpendAllowance uses one call of an approved allowance requester holds for operation on connection, returning its id; ok is false when none has a call left before its deadline, and then the policy decides again.

func (*Service) Submit

func (s *Service) Submit(ctx context.Context, actor Actor, in Submit) (*Request, error)

Submit files a request for actor: the script's owner, or an administrator, asking for one of its versions.

func (*Service) SubmitCall added in v1.161.0

func (s *Service) SubmitCall(ctx context.Context, actor Actor, in CallRequest) (*Request, error)

SubmitCall files a held call for actor, who made it. A request is frozen when filed: nothing changes its arguments afterward.

func (*Service) SubmitEnvironment added in v1.158.0

func (s *Service) SubmitEnvironment(ctx context.Context, actor Actor, in SubmitEnvironment) (*Request, error)

SubmitEnvironment files a request to make a site environment's domain public, or to redirect the environment (#2632), or returns the one already waiting.

func (*Service) SubmitRelease added in v1.155.0

func (s *Service) SubmitRelease(ctx context.Context, actor Actor, in SubmitRelease) (*Request, error)

SubmitRelease files a request to serve a site release in an environment that requires approval (#2518), or returns the one already waiting.

type Store

type Store interface {
	Insert(ctx context.Context, r *Request) error
	Get(ctx context.Context, id string) (*Request, error)
	List(ctx context.Context, f Filter) ([]Request, error)
	// Decide records a pending request's decision, refusing one that is not
	// pending with ErrDecided.
	Decide(ctx context.Context, id string, d Decision) (*Request, error)
	// LatestApproved is the highest version approved for a script and
	// purpose, ErrNotFound for none.
	LatestApproved(ctx context.Context, scriptID, purpose string) (*Request, error)
	// ReleaseApproved reports whether a site release is approved for a
	// target at the digest.
	ReleaseApproved(ctx context.Context, releaseID, target, digest string) (bool, error)
	// EnvironmentApproved reports whether making a site environment public
	// is approved for the access stamp.
	EnvironmentApproved(ctx context.Context, siteID, target, stamp string) (bool, error)
}

Store keeps requests.

type Submit

type Submit struct {
	// Script is the script's id, or the name of one of the requester's own.
	Script  string
	Version int
	Purpose string
	Reason  string
}

Submit is what a requester asks for.

type SubmitEnvironment added in v1.158.0

type SubmitEnvironment struct {
	SiteID string
	Site   string
	Target string
	// Stamp is the environment's access when asked: an approval holds for it
	// alone.
	Stamp  string
	Reason string
	// Purpose is PurposeSitePublic (the default) or PurposeSiteRedirect.
	Purpose string
}

SubmitEnvironment asks to make a site environment that requires approval public (#2604).

type SubmitRelease added in v1.155.0

type SubmitRelease struct {
	ReleaseID string
	Site      string
	Number    int
	Target    string
	Digest    string
	Reason    string
}

SubmitRelease names the site release a promotion waits on.

Directories

Path Synopsis
Package apprhttp serves the Approvals queue on the portal (#2437, #2494): a person's own requests, every request for an administrator, filing one and deciding one, through the service manage_approval uses and under its rules.
Package apprhttp serves the Approvals queue on the portal (#2437, #2494): a person's own requests, every request for an administrator, filing one and deciding one, through the service manage_approval uses and under its rules.
Package apprtool is the manage_approval MCP tool (#2437, #2494): submitting a request, listing requests and deciding one are commands of one tool, over the service the portal's Approvals page uses.
Package apprtool is the manage_approval MCP tool (#2437, #2494): submitting a request, listing requests and deciding one are commands of one tool, over the service the portal's Approvals page uses.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL