Merge branch 'worktree-agent-a82ec64b6cc1a2809'

# Conflicts:
#	internal/app/archie/operations.go
#	modules/events/events.go
#	modules/governance/accounts_api.go
#	modules/governance/governance.go
This commit is contained in:
sam committed 2026-11-22 02:16:56 +11:00
commit e3130d53e7
44 files changed
+1462 -266

No files matched your search

+113
View File
@@ -0,0 +1,113 @@
package archie
import (
"context"
"errors"
"net/http"
"net/http/httptest"
"regexp"
"slices"
"testing"
"github.com/samcharles93/archie-core/internal/platform/httpapi"
"github.com/samcharles93/archie-core/modules/governance"
)
// operator authenticates every request as an instance administrator.
type operator struct{}
func (operator) Authenticate(ctx context.Context, _ *http.Request) (context.Context, bool, error) {
return ctx, true, nil
}
// refuses answers every Allow with err and records what it was asked.
type refuses struct {
err error
asked []string
}
func (r *refuses) Allow(_ context.Context, action, kind string) error {
r.asked = append(r.asked, action+" "+kind)
return r.err
}
// publicOperations are the only operations a caller reaches without a
// credential: sign-in, setup and the auth status the sign-in page reads.
var publicOperations = []string{
"begin-oidc-sign-in", "begin-passkey-sign-in", "finish-oidc-sign-in", "finish-passkey-sign-in",
"get-auth-status", "recover-account", "set-up-account", "sign-in", "sign-out",
}
var pathParam = regexp.MustCompile(`\{[^}]+\}`)
// TestEveryOperationIsAuthorized guards deny-by-default across every module's
// routes. Each registered operation is either one of the named public
// operations or declares a valid action and resource kind, and a request that
// fails the grant, or that cannot be decided, is refused before its handler
// runs. The handlers here have nothing behind them, so one that ran would
// panic.
func TestEveryOperationIsAuthorized(t *testing.T) {
probe := &refuses{err: httpapi.ErrDenied}
mux, api := emptyAPI(operator{}, probe)
routes := httpapi.Routes(api)
if len(routes) < 100 {
t.Fatalf("only %d operations registered", len(routes))
}
var public []string
for _, route := range routes {
if route.Access.IsPublic() {
public = append(public, route.ID)
continue
}
action, kind, ok := route.Access.Declared()
if !ok {
t.Errorf("%s declares no access", route.ID)
continue
}
if err := governance.Action(action).Validate(); err != nil || kind == "" {
t.Errorf("%s declares %q on %q", route.ID, action, kind)
}
}
slices.Sort(public)
if !slices.Equal(public, publicOperations) {
t.Errorf("public operations = %v, want %v", public, publicOperations)
}
for _, tt := range []struct {
name string
err error
want int
}{
{"a failing grant", httpapi.ErrDenied, http.StatusForbidden},
{"an unavailable policy chain", httpapi.ErrUnavailable, http.StatusServiceUnavailable},
} {
t.Run(tt.name, func(t *testing.T) {
for _, route := range routes {
action, kind, ok := route.Access.Declared()
if !ok {
continue
}
probe.err, probe.asked = tt.err, nil
req := httptest.NewRequestWithContext(t.Context(), route.Method, pathParam.ReplaceAllString(route.Path, "x"), nil)
rec := httptest.NewRecorder()
mux.ServeHTTP(rec, req)
if rec.Code != tt.want {
t.Errorf("%s: status = %d, want %d", route.ID, rec.Code, tt.want)
}
if want := []string{action + " " + kind}; !slices.Equal(probe.asked, want) {
t.Errorf("%s: decided on %v, want %v", route.ID, probe.asked, want)
}
}
})
}
}
// TestUnwiredAuthorizerRefuses guards the boot order: until the policy chain
// is wired, an authorized operation is refused rather than let through.
func TestUnwiredAuthorizerRefuses(t *testing.T) {
settings := &governance.Module{}
if err := settings.Allow(governance.WithPrincipal(t.Context(), governance.SharedTokenOwner()), "read", "run"); !errors.Is(err, httpapi.ErrUnavailable) {
t.Fatalf("Allow with no chain = %v, want %v", err, httpapi.ErrUnavailable)
}
}
+10 -2
View File
@@ -68,7 +68,15 @@ func (m apiModules) register(api huma.API) {
// needs no database.
func Document() ([]byte, error) {
settings := &governance.Module{}
api := httpapi.New(http.NewServeMux(), buildinfo.Version, settings.Authenticator(""))
_, api := emptyAPI(settings.Authenticator(""), settings)
return api.OpenAPI().YAML()
}
// emptyAPI registers every route on modules with nothing behind them.
func emptyAPI(auth httpapi.Authenticator, authz httpapi.Authorizer) (*http.ServeMux, huma.API) {
mux := http.NewServeMux()
settings := &governance.Module{}
api := httpapi.New(mux, buildinfo.Version, auth, authz)
apiModules{
settings: settings, conns: &connectors.Module{}, system: &system.Module{},
tell: &deliveries.Module{}, allow: &approvals.Module{}, classes: &judgement.Classes{},
@@ -76,5 +84,5 @@ func Document() ([]byte, error) {
engine: &runs.Engine{}, chat: &chat.Module{}, drafts: &drafts.Module{},
notes: &memory.Module{}, live: hub.New(),
}.register(api)
return api.OpenAPI().YAML()
return mux, api
}
+11 -4
View File
@@ -55,11 +55,15 @@ func (o *operations) Start(ctx context.Context) error {
if err != nil {
return err
}
// Every entry point asks the same chain, and each refusal is stored as a
// denial.
checked := governance.Recording(access, o.settings, o.log.With("module", "governance"))
// A workflow takes its context from the run handle, as a handler takes it
// from the request.
o.engine.Use(runs.Deps{
Settings: o.settings, Toolbox: o.conns, Judge: o.judge, Approver: o.allow,
Notifier: o.tell, Messenger: o.tell, Memory: o.remember, Capabilities: o.conns,
Access: checked,
})
if err := installStarter(ctx, o.engine); err != nil {
return err
@@ -76,10 +80,13 @@ func (o *operations) Start(ctx context.Context) error {
// Nothing below can fail, so a retry cannot launch a connector or a loop twice.
o.checks.Register("connectors", o.conns.Ready)
// Administrative writes are checked against the same live policy chain as
// every other request.
o.settings.UseAuthorizer(access)
o.allow.UseAuthorizer(access)
// Administrative writes, and every API request, are checked against the same
// live policy chain as chat and background work. The webhook intake applies
// each source's delivery policy from it.
o.settings.UseAuthorizer(checked)
o.allow.UseAuthorizer(checked)
o.tell.UseAccess(checked)
o.hear.UseDeliveryPolicy(access)
o.talk.Use(chat.Deps{
People: o.settings, Access: access, Settings: o.settings, Toolbox: o.conns, Judge: o.judge,
Approver: o.allow, Memory: o.remember, Runs: o.engine, Notifier: o.tell,
+1 -1
View File
@@ -151,7 +151,7 @@ func wire(log *slog.Logger, configPath string, cfg Config, db *sqlx.DB) (*binary
runtime.RegisterBuiltinClasses()
settings := governance.NewModule(db, log.With("module", "governance"), orgID)
mux := http.NewServeMux()
api := httpapi.New(mux, buildinfo.Version, settings.Authenticator(cfg.AdminTokenSHA256))
api := httpapi.New(mux, buildinfo.Version, settings.Authenticator(cfg.AdminTokenSHA256), settings)
conns, err := connectors.NewModule(db, log.With("module", "connectors"), orgID, connectors.Sealing{
Identity: cfg.AgeIdentity, Backups: cfg.AgeBackupRecipients,
+123 -27
View File
@@ -43,50 +43,120 @@ func OK[T any](v T) *Reply[T] {
return &Reply[T]{Body: v}
}
type access int
// ErrDenied is what an Authorizer returns when the caller's grant does not
// cover the operation.
var ErrDenied = errors.New("not permitted")
// ErrUnavailable is what an Authorizer returns when it cannot decide, such as
// when the policy chain is not loaded. The operation is then refused.
var ErrUnavailable = errors.New("authorization is unavailable")
// Authorizer decides whether the caller acting in ctx may take action on a
// resource of kind. It returns ErrDenied, ErrUnavailable or nil.
type Authorizer interface {
Allow(ctx context.Context, action, kind string) error
}
type accessKind int
const (
accessAdmin access = iota
accessSignedIn
// accessUnset is the zero Access. An operation holding it is refused, so
// an operation that declares nothing never runs.
accessUnset accessKind = iota
accessPublic
accessAuthorized
)
// Access is how an operation is guarded. Register requires one, and the zero
// value refuses every request.
type Access struct {
kind accessKind
action string
resource string
admin bool
}
// Public is an operation callable without a credential: liveness, setup and
// sign-in.
func Public() Access { return Access{kind: accessPublic} }
// Authorized is an operation that needs an authenticated caller whose grant
// covers action on a resource of kind, as the policy chain decides.
func Authorized[A, K ~string](action A, kind K) Access {
return Access{kind: accessAuthorized, action: string(action), resource: string(kind)}
}
// AdminAuthorized is Authorized for an operation that also needs an instance
// administrator, whatever the policy chain would allow.
func AdminAuthorized[A, K ~string](action A, kind K) Access {
a := Authorized(action, kind)
a.admin = true
return a
}
// Declared reports the action and resource kind an authorized operation is
// decided on, and false for any other operation.
func (a Access) Declared() (action, kind string, ok bool) {
return a.action, a.resource, a.kind == accessAuthorized
}
// IsPublic reports whether the operation needs no credential.
func (a Access) IsPublic() bool { return a.kind == accessPublic }
const accessKey = "archie-access"
// Public marks op as callable without a credential: signing in, for one.
func Public(op huma.Operation) huma.Operation {
op.Security = []map[string][]string{{}}
return withAccess(op, accessPublic)
}
// SignedIn marks op as callable by any authenticated caller. Every other
// operation needs an instance administrator.
func SignedIn(op huma.Operation) huma.Operation {
return withAccess(op, accessSignedIn)
}
func withAccess(op huma.Operation, a access) huma.Operation {
// Register adds an operation guarded as access says. It is the only way to
// register one on this API, so every operation declares who may call it.
func Register[I, O any](api huma.API, access Access, op huma.Operation, handler func(context.Context, *I) (*O, error)) {
if op.Metadata == nil {
op.Metadata = map[string]any{}
}
op.Metadata[accessKey] = a
return op
op.Metadata[accessKey] = access
if access.kind == accessPublic {
op.Security = []map[string][]string{{}}
}
huma.Register(api, op, handler)
}
func accessOf(op *huma.Operation) access {
// AccessOf returns how a registered operation is guarded. An operation not
// registered through Register has the zero Access.
func AccessOf(op *huma.Operation) Access {
if op == nil {
return accessAdmin
return Access{}
}
a, _ := op.Metadata[accessKey].(access)
a, _ := op.Metadata[accessKey].(Access)
return a
}
// Route is a registered operation and how it is guarded.
type Route struct {
ID, Method, Path string
Access Access
}
// Routes returns every operation registered on api with how it is guarded.
func Routes(api huma.API) []Route {
var out []Route
for p, item := range api.OpenAPI().Paths {
for method, op := range map[string]*huma.Operation{
http.MethodGet: item.Get, http.MethodPut: item.Put, http.MethodPost: item.Post,
http.MethodDelete: item.Delete, http.MethodPatch: item.Patch, http.MethodHead: item.Head,
http.MethodOptions: item.Options, http.MethodTrace: item.Trace,
} {
if op != nil {
out = append(out, Route{ID: op.OperationID, Method: method, Path: p, Access: AccessOf(op)})
}
}
}
return out
}
// New returns an API on mux whose operations authenticate through auth.
// Every unsafe request must also pass cross-origin protection, since a
// browser sends the session cookie with any request to this origin.
func New(mux *http.ServeMux, version string, auth Authenticator) huma.API {
func New(mux *http.ServeMux, version string, auth Authenticator, authz Authorizer) huma.API {
api := humago.New(mux, config(version))
api.UseMiddleware(guard(api, auth, http.NewCrossOriginProtection()))
api.UseMiddleware(guard(api, auth, authz, http.NewCrossOriginProtection()))
return api
}
@@ -106,17 +176,22 @@ func config(version string) huma.Config {
return cfg
}
func guard(api huma.API, auth Authenticator, origins *http.CrossOriginProtection) func(huma.Context, func(huma.Context)) {
func guard(api huma.API, auth Authenticator, authz Authorizer, origins *http.CrossOriginProtection) func(huma.Context, func(huma.Context)) {
return func(ctx huma.Context, next func(huma.Context)) {
r, _ := humago.Unwrap(ctx)
if err := origins.Check(r); err != nil {
_ = huma.WriteErr(api, ctx, http.StatusForbidden, "cross-origin request refused")
return
}
need := accessOf(ctx.Operation())
if need == accessPublic {
need := AccessOf(ctx.Operation())
switch need.kind {
case accessPublic:
next(ctx)
return
case accessAuthorized:
default:
_ = huma.WriteErr(api, ctx, http.StatusForbidden, "operation declares no access")
return
}
acting, admin, err := auth.Authenticate(ctx.Context(), r)
switch {
@@ -127,14 +202,35 @@ func guard(api huma.API, auth Authenticator, origins *http.CrossOriginProtection
case err != nil:
_ = huma.WriteErr(api, ctx, http.StatusServiceUnavailable, "authentication is unavailable")
return
case need == accessAdmin && !admin:
case need.admin && !admin:
_ = huma.WriteErr(api, ctx, http.StatusForbidden, "instance administrator required")
return
}
if status, msg := decide(acting, authz, need); status != 0 {
_ = huma.WriteErr(api, ctx, status, msg)
return
}
next(huma.WithContext(ctx, acting))
}
}
// decide asks authz whether the authenticated caller may take the declared
// action. It returns a status of 0 to let the request through. With no
// authorizer the operation is refused.
func decide(acting context.Context, authz Authorizer, need Access) (status int, message string) {
if authz == nil {
return http.StatusServiceUnavailable, ErrUnavailable.Error()
}
switch err := authz.Allow(acting, need.action, need.resource); {
case err == nil:
return 0, ""
case errors.Is(err, ErrDenied):
return http.StatusForbidden, ErrDenied.Error()
default:
return http.StatusServiceUnavailable, ErrUnavailable.Error()
}
}
// schemaName prefixes a type of Archie's own with its package, since modules
// reuse short names like Source and Request.
func schemaName(t reflect.Type, hint string) string {
+101 -31
View File
@@ -26,46 +26,88 @@ func (headerAuth) Authenticate(ctx context.Context, r *http.Request) (context.Co
}
}
// TestOperationAccess guards the API's authentication boundary: public
// operations need no credential, every other operation needs one, only an
// instance administrator reaches an operation not marked otherwise, and a
// cross-origin browser request cannot use the session cookie to change
// anything.
// grants answers Allow from a fixed set of "action kind" pairs and records
// what it was asked.
type grants struct {
allowed map[string]bool
err error
asked []string
}
func (g *grants) Allow(_ context.Context, action, kind string) error {
g.asked = append(g.asked, action+" "+kind)
switch {
case g.err != nil:
return g.err
case g.allowed[action+" "+kind]:
return nil
}
return ErrDenied
}
// TestOperationAccess guards the API's enforcement boundary: public
// operations need no credential, every other operation needs one and a grant
// from the authorizer before its handler runs, an operation that declares no
// access never runs, and a cross-origin browser request cannot use the
// session cookie to change anything.
func TestOperationAccess(t *testing.T) {
tests := []struct {
name, method, path, caller, fetchSite string
grants *grants
noAuthorizer bool
want int
wantRan bool
}{
{name: "public without a credential", method: http.MethodGet, path: "/public", want: http.StatusOK},
{name: "public sign-in from this origin", method: http.MethodPost, path: "/public", fetchSite: "same-origin", want: http.StatusOK},
{name: "public without a credential", method: http.MethodGet, path: "/public", want: http.StatusOK, wantRan: true},
{name: "public sign-in from this origin", method: http.MethodPost, path: "/public", fetchSite: "same-origin", want: http.StatusOK, wantRan: true},
{name: "public sign-in from another origin", method: http.MethodPost, path: "/public", fetchSite: "cross-site", want: http.StatusForbidden},
{name: "signed-in without a credential", method: http.MethodGet, path: "/signed-in", want: http.StatusUnauthorized},
{name: "signed-in as a person", method: http.MethodGet, path: "/signed-in", caller: "person", want: http.StatusOK},
{name: "a stream without a credential", method: http.MethodGet, path: "/stream", want: http.StatusUnauthorized},
{name: "a stream as a person", method: http.MethodGet, path: "/stream", caller: "person", want: http.StatusOK},
{name: "admin without a credential", method: http.MethodGet, path: "/admin", want: http.StatusUnauthorized},
{name: "admin as a person", method: http.MethodGet, path: "/admin", caller: "person", want: http.StatusForbidden},
{name: "admin as the admin", method: http.MethodGet, path: "/admin", caller: "admin", want: http.StatusOK},
{name: "mutation from this origin", method: http.MethodPost, path: "/admin", caller: "admin", fetchSite: "same-origin", want: http.StatusOK},
{name: "mutation from another origin", method: http.MethodPost, path: "/admin", caller: "admin", fetchSite: "cross-site", want: http.StatusForbidden},
{name: "a failed lookup is not a refusal", method: http.MethodGet, path: "/admin", caller: "broken", want: http.StatusServiceUnavailable},
{name: "authorized without a credential", method: http.MethodGet, path: "/read", want: http.StatusUnauthorized},
{name: "authorized and granted", method: http.MethodGet, path: "/read", caller: "person", grants: &grants{allowed: map[string]bool{"read thing": true}}, want: http.StatusOK, wantRan: true},
{name: "authorized but not granted", method: http.MethodGet, path: "/read", caller: "person", grants: &grants{}, want: http.StatusForbidden},
{name: "authorized while the chain is unavailable", method: http.MethodGet, path: "/read", caller: "person", grants: &grants{err: ErrUnavailable}, want: http.StatusServiceUnavailable},
{name: "authorized when the authorizer fails", method: http.MethodGet, path: "/read", caller: "person", grants: &grants{err: errors.New("database down")}, want: http.StatusServiceUnavailable},
{name: "authorized with no authorizer", method: http.MethodGet, path: "/read", caller: "admin", noAuthorizer: true, want: http.StatusServiceUnavailable},
{name: "a stream not granted", method: http.MethodGet, path: "/stream", caller: "person", grants: &grants{}, want: http.StatusForbidden},
{name: "a stream granted", method: http.MethodGet, path: "/stream", caller: "person", grants: &grants{allowed: map[string]bool{"read thing": true}}, want: http.StatusOK, wantRan: true},
{name: "admin operation as a person with the grant", method: http.MethodGet, path: "/admin", caller: "person", grants: &grants{allowed: map[string]bool{"update thing": true}}, want: http.StatusForbidden},
{name: "admin operation as the admin without the grant", method: http.MethodGet, path: "/admin", caller: "admin", grants: &grants{}, want: http.StatusForbidden},
{name: "admin operation as the admin with the grant", method: http.MethodGet, path: "/admin", caller: "admin", grants: &grants{allowed: map[string]bool{"update thing": true}}, want: http.StatusOK, wantRan: true},
{name: "an operation that declares nothing", method: http.MethodGet, path: "/undeclared", caller: "admin", grants: &grants{allowed: map[string]bool{" ": true}}, want: http.StatusForbidden},
{name: "mutation from this origin", method: http.MethodPost, path: "/admin", caller: "admin", fetchSite: "same-origin", grants: &grants{allowed: map[string]bool{"update thing": true}}, want: http.StatusOK, wantRan: true},
{name: "mutation from another origin", method: http.MethodPost, path: "/admin", caller: "admin", fetchSite: "cross-site", grants: &grants{allowed: map[string]bool{"update thing": true}}, want: http.StatusForbidden},
{name: "a failed lookup is not a refusal", method: http.MethodGet, path: "/read", caller: "broken", grants: &grants{}, want: http.StatusServiceUnavailable},
}
mux := http.NewServeMux()
api := New(mux, "test", headerAuth{})
reached := func(context.Context, *struct{}) (*Reply[string], error) { return OK("reached"), nil }
for _, method := range []string{http.MethodGet, http.MethodPost} {
huma.Register(api, Public(huma.Operation{OperationID: "public-" + method, Method: method, Path: "/public"}), reached)
huma.Register(api, SignedIn(huma.Operation{OperationID: "signed-in-" + method, Method: method, Path: "/signed-in"}), reached)
huma.Register(api, huma.Operation{OperationID: "admin-" + method, Method: method, Path: "/admin"}, reached)
}
// A streamed response writes its own status, so it must still pass the
// guard before its body runs.
huma.Register(api, SignedIn(huma.Operation{OperationID: "stream", Method: http.MethodGet, Path: "/stream"}),
func(context.Context, *struct{}) (*huma.StreamResponse, error) {
return &huma.StreamResponse{Body: func(hc huma.Context) { hc.SetStatus(http.StatusOK) }}, nil
})
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
mux := http.NewServeMux()
var authz Authorizer
if !tt.noAuthorizer {
if tt.grants == nil {
tt.grants = &grants{}
}
authz = tt.grants
}
api := New(mux, "test", headerAuth{}, authz)
ran := false
reached := func(context.Context, *struct{}) (*Reply[string], error) {
ran = true
return OK("reached"), nil
}
for _, method := range []string{http.MethodGet, http.MethodPost} {
Register(api, Public(), huma.Operation{OperationID: "public-" + method, Method: method, Path: "/public"}, reached)
Register(api, Authorized("read", "thing"), huma.Operation{OperationID: "read-" + method, Method: method, Path: "/read"}, reached)
Register(api, AdminAuthorized("update", "thing"), huma.Operation{OperationID: "admin-" + method, Method: method, Path: "/admin"}, reached)
// A direct huma registration declares no access.
huma.Register(api, huma.Operation{OperationID: "undeclared-" + method, Method: method, Path: "/undeclared"}, reached)
}
// A streamed response writes its own status, so it must still pass
// the guard before its body runs.
Register(api, Authorized("read", "thing"), huma.Operation{OperationID: "stream", Method: http.MethodGet, Path: "/stream"},
func(context.Context, *struct{}) (*huma.StreamResponse, error) {
ran = true
return &huma.StreamResponse{Body: func(hc huma.Context) { hc.SetStatus(http.StatusOK) }}, nil
})
req := httptest.NewRequestWithContext(t.Context(), tt.method, tt.path, nil)
if tt.caller != "" {
req.Header.Set("X-Test-Caller", tt.caller)
@@ -78,6 +120,34 @@ func TestOperationAccess(t *testing.T) {
if rec.Code != tt.want {
t.Fatalf("status = %d, want %d: %s", rec.Code, tt.want, rec.Body)
}
if ran != tt.wantRan {
t.Fatalf("handler ran = %v, want %v", ran, tt.wantRan)
}
})
}
}
// TestOperationsDeclareAccess guards the registry the route table is checked
// from: an operation registered through Register reports what it declared, and
// one registered directly reports none.
func TestOperationsDeclareAccess(t *testing.T) {
api := New(http.NewServeMux(), "test", headerAuth{}, nil)
noop := func(context.Context, *struct{}) (*Reply[string], error) { return OK(""), nil }
Register(api, Public(), huma.Operation{OperationID: "p", Method: http.MethodGet, Path: "/p"}, noop)
Register(api, Authorized("read", "thing"), huma.Operation{OperationID: "a", Method: http.MethodGet, Path: "/a"}, noop)
huma.Register(api, huma.Operation{OperationID: "u", Method: http.MethodGet, Path: "/u"}, noop)
got := map[string]Access{}
for _, r := range Routes(api) {
got[r.ID] = r.Access
}
if !got["p"].IsPublic() {
t.Error("p is not public")
}
if action, kind, ok := got["a"].Declared(); !ok || action != "read" || kind != "thing" {
t.Errorf("a declares %q %q %v", action, kind, ok)
}
if _, _, ok := got["u"].Declared(); ok || got["u"].IsPublic() {
t.Error("u declares access it never registered")
}
}
+5 -5
View File
@@ -117,18 +117,18 @@ func (m *Module) confirmed(ctx context.Context, row store.Request, a *Assertion)
// Register adds the approvals API.
func (m *Module) Register(api huma.API) {
tags := []string{"Approvals"}
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindApproval), huma.Operation{
OperationID: "list-approvals", Method: http.MethodGet, Path: "/api/approvals",
Summary: "List approval requests waiting for an answer", Tags: tags,
}, m.list)
huma.Register(api, httpapi.SignedIn(huma.Operation{
httpapi.Register(api, httpapi.Authorized(governance.ActionApprove, governance.KindApproval), huma.Operation{
OperationID: "answer-approval", Method: http.MethodPost, Path: "/api/approvals/{id}/answer",
Summary: "Approve or refuse an action as the signed-in person", Tags: tags,
}), m.answer)
huma.Register(api, httpapi.SignedIn(huma.Operation{
}, m.answer)
httpapi.Register(api, httpapi.Authorized(governance.ActionApprove, governance.KindApproval), huma.Operation{
OperationID: "begin-approval-confirmation", Method: http.MethodPost, Path: "/api/approvals/{id}/confirmation",
Summary: "Start the passkey confirmation that approving an irreversible action needs", Tags: tags,
}), m.beginConfirmation)
}, m.beginConfirmation)
}
type answerInput struct {
+6 -1
View File
@@ -356,7 +356,7 @@ func chatServer(t *testing.T, session, turn uuid.UUID) *httptest.Server {
wake: make(chan struct{}, 1), running: map[uuid.UUID]context.CancelFunc{},
}
mux := http.NewServeMux()
m.Register(httpapi.New(mux, "test", headerAuth{}))
m.Register(httpapi.New(mux, "test", headerAuth{}, allowAll{}))
srv := httptest.NewServer(mux)
t.Cleanup(srv.Close)
return srv
@@ -569,3 +569,8 @@ func (f *fakeStore) EventsOf(context.Context, uuid.UUID, []string) ([]store.Even
// noPrivilegedEffects is a declaration that states it has no privileged effect,
// the only kind chat offers.
var noPrivilegedEffects = connectors.PrivilegedEffects{Declared: true}
// allowAll leaves every decision to the handlers under test.
type allowAll struct{}
func (allowAll) Allow(context.Context, string, string) error { return nil }
+18 -18
View File
@@ -28,40 +28,40 @@ const (
// Register adds the chat API.
func (m *Module) Register(api huma.API) {
tags := []string{"Chat"}
huma.Register(api, httpapi.SignedIn(huma.Operation{
httpapi.Register(api, httpapi.Authorized(governance.ActionRead, governance.KindChatSession), huma.Operation{
OperationID: "list-chat-sessions", Method: http.MethodGet, Path: "/api/chat/sessions",
Summary: "List conversations, most recently active first, with the model that answers", Tags: tags,
}), m.listSessions)
huma.Register(api, httpapi.SignedIn(huma.Operation{
}, m.listSessions)
httpapi.Register(api, httpapi.Authorized(governance.ActionCreate, governance.KindChatSession), huma.Operation{
OperationID: "create-chat-session", Method: http.MethodPost, Path: "/api/chat/sessions",
Summary: "Start a conversation", Tags: tags, DefaultStatus: http.StatusCreated,
}), m.createSession)
huma.Register(api, httpapi.SignedIn(huma.Operation{
}, m.createSession)
httpapi.Register(api, httpapi.Authorized(governance.ActionUpdate, governance.KindChatSession), huma.Operation{
OperationID: "rename-chat-session", Method: http.MethodPatch, Path: "/api/chat/sessions/{id}",
Summary: "Rename a conversation", Tags: tags,
}), m.renameSession)
huma.Register(api, httpapi.SignedIn(huma.Operation{
}, m.renameSession)
httpapi.Register(api, httpapi.Authorized(governance.ActionDelete, governance.KindChatSession), huma.Operation{
OperationID: "delete-chat-session", Method: http.MethodDelete, Path: "/api/chat/sessions/{id}",
Summary: "Delete a conversation and its turns", Tags: tags, DefaultStatus: http.StatusNoContent,
}), m.deleteSession)
huma.Register(api, httpapi.SignedIn(huma.Operation{
}, m.deleteSession)
httpapi.Register(api, httpapi.Authorized(governance.ActionRead, governance.KindChatSession), huma.Operation{
OperationID: "list-chat-turns", Method: http.MethodGet, Path: "/api/chat/sessions/{id}/turns",
Summary: "List a conversation's turns with what each did", Tags: tags,
}), m.listTurns)
huma.Register(api, httpapi.SignedIn(huma.Operation{
}, m.listTurns)
httpapi.Register(api, httpapi.Authorized(governance.ActionCreate, governance.KindChatSession), huma.Operation{
OperationID: "send-chat-turn", Method: http.MethodPost, Path: "/api/chat/sessions/{id}/turns",
Summary: "Send a message; it is stored, then answered after the turns before it", Tags: tags,
DefaultStatus: http.StatusAccepted,
}), m.sendTurn)
huma.Register(api, httpapi.SignedIn(huma.Operation{
}, m.sendTurn)
httpapi.Register(api, httpapi.Authorized(governance.ActionRead, governance.KindChatSession), huma.Operation{
OperationID: "get-chat-turn", Method: http.MethodGet, Path: "/api/chat/turns/{id}",
Summary: "Get one turn with what it did", Tags: tags,
}), m.getTurn)
huma.Register(api, httpapi.SignedIn(huma.Operation{
}, m.getTurn)
httpapi.Register(api, httpapi.Authorized(governance.ActionUpdate, governance.KindChatSession), huma.Operation{
OperationID: "cancel-chat-turn", Method: http.MethodPost, Path: "/api/chat/turns/{id}/cancel",
Summary: "Stop a turn that is queued or running", Tags: tags,
}), m.cancelTurn)
huma.Register(api, httpapi.SignedIn(huma.Operation{
}, m.cancelTurn)
httpapi.Register(api, httpapi.Authorized(governance.ActionRead, governance.KindChatSession), huma.Operation{
OperationID: "stream-chat-turn", Method: http.MethodGet, Path: "/api/chat/turns/{id}/events",
Summary: "Stream what a turn records, from a cursor, until it ends", Tags: tags,
Responses: map[string]*huma.Response{"200": {
@@ -70,7 +70,7 @@ func (m *Module) Register(api huma.API) {
"the stream ends after done, error or cancelled.",
Content: map[string]*huma.MediaType{"text/event-stream": {Schema: &huma.Schema{Type: huma.TypeString}}},
}},
}), m.streamTurn)
}, m.streamTurn)
}
// Sessions is the conversation list with the model that answers turns.
+10 -9
View File
@@ -22,6 +22,7 @@ import (
"github.com/samcharles93/archie-core/internal/platform/httpapi"
"github.com/samcharles93/archie-core/internal/platform/seal"
"github.com/samcharles93/archie-core/modules/connectors/internal/store"
"github.com/samcharles93/archie-core/modules/governance"
)
// validName is the shape of a connector name: it appears in logs and URLs.
@@ -330,46 +331,46 @@ func listExtensionKinds(context.Context, *struct{}) (*httpapi.Reply[[]ExtensionK
// Register adds the API for accepted packages and credentials.
func (m *Module) Register(api huma.API) {
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindConnector), huma.Operation{
OperationID: "list-extension-kinds", Method: http.MethodGet, Path: "/api/extension-kinds",
Summary: "List the kinds of extension and the group each belongs to", Tags: []string{"Connectors"},
}, listExtensionKinds)
for _, k := range extensionKinds() {
tags := []string{k.tag}
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindConnector), huma.Operation{
OperationID: "list-" + k.noun + "s", Method: http.MethodGet, Path: k.path,
Summary: "List accepted " + k.plural, Tags: tags,
}, m.list(k.contract))
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionDelete, governance.KindConnector), huma.Operation{
OperationID: "remove-" + k.noun, Method: http.MethodDelete, Path: k.path + "/{name}",
Summary: "Remove an accepted package", Tags: tags,
}, m.remove(k.contract))
if k.contract == store.ContractMCP {
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindMCPServer), huma.Operation{
OperationID: "accept-mcp-server", Method: http.MethodPut, Path: k.path + "/{name}",
Summary: "Accept an MCP server and the tools it may offer", Tags: tags,
}, m.acceptServer)
continue
}
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindConnector), huma.Operation{
OperationID: "accept-" + k.noun, Method: http.MethodPut, Path: k.path + "/{name}",
Summary: "Accept a package and start it", Tags: tags,
}, m.accept(k.contract))
}
tags := []string{"Credentials"}
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindSecret), huma.Operation{
OperationID: "list-credentials", Method: http.MethodGet, Path: "/api/credentials",
Summary: "List credentials, never their values", Tags: tags,
}, m.listCredentials)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindSecret), huma.Operation{
OperationID: "get-credential", Method: http.MethodGet, Path: "/api/credentials/{name}",
Summary: "Get a credential, never its values", Tags: tags,
}, m.getCredential)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindSecret), huma.Operation{
OperationID: "put-credential", Method: http.MethodPut, Path: "/api/credentials/{name}",
Summary: "Store a credential sealed and restart what uses it", Tags: tags,
}, m.putCredential)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindSecret), huma.Operation{
OperationID: "list-credential-kinds", Method: http.MethodGet, Path: "/api/credential-kinds",
Summary: "List credential kinds and the fields each takes", Tags: tags,
}, listCredentialKinds)
+2 -2
View File
@@ -27,14 +27,14 @@ const chatOutcome = `data: {"topic":"tasks","data":{"kind":"chat_outcome"}}` + "
// streams from the chat API. Keepalives tell the connection indicator the
// server is up, and a reconnect makes every mounted page re-read.
func Register(api huma.API, h *hub.Hub) {
huma.Register(api, httpapi.SignedIn(huma.Operation{
httpapi.Register(api, httpapi.Authorized(governance.ActionRead, governance.KindDashboard), huma.Operation{
OperationID: "stream-dashboard", Method: http.MethodGet, Path: "/api/stream",
Summary: "Stream live dashboard updates", Tags: []string{"Dashboard"},
Responses: map[string]*huma.Response{"200": {
Description: "Server-sent events: one data frame of {\"topic\", \"data\"} per update, and a keepalive comment while idle",
Content: map[string]*huma.MediaType{"text/event-stream": {Schema: &huma.Schema{Type: huma.TypeString}}},
}},
}), func(ctx context.Context, _ *struct{}) (*huma.StreamResponse, error) {
}, func(ctx context.Context, _ *struct{}) (*huma.StreamResponse, error) {
// A conversation is its owner's; nobody else hears that it changed.
var chat <-chan hub.Note
stop := func() {}
+6 -1
View File
@@ -30,7 +30,7 @@ func TestStreamTellsOnlyTheConversationsOwner(t *testing.T) {
t.Run(tc.reader, func(t *testing.T) {
h := hub.New()
mux := http.NewServeMux()
Register(httpapi.New(mux, "test", headerAuth{}), h)
Register(httpapi.New(mux, "test", headerAuth{}, allowAll{}), h)
srv := httptest.NewServer(mux)
defer srv.Close()
@@ -75,3 +75,8 @@ func (headerAuth) Authenticate(ctx context.Context, r *http.Request) (context.Co
}
return governance.WithPrincipal(ctx, p), p.InstanceAdmin(), nil
}
// allowAll leaves every decision to the handlers under test.
type allowAll struct{}
func (allowAll) Allow(context.Context, string, string) error { return nil }
+107
View File
@@ -0,0 +1,107 @@
package deliveries
import (
"context"
"log/slog"
"slices"
"strings"
"testing"
"time"
"github.com/google/uuid"
"github.com/samcharles93/archie-core/modules/connectors"
"github.com/samcharles93/archie-core/modules/deliveries/internal/store"
"github.com/samcharles93/archie-core/modules/governance"
)
// sequencedAccess answers each Authorize with the next decision, the last one
// repeating, and records what was asked.
type sequencedAccess struct {
decisions []governance.Decision
asked []string
}
func (s *sequencedAccess) Authorize(_ context.Context, p governance.Principal, a governance.Action, r governance.Resource, _ governance.AccessContext) governance.Decision {
s.asked = append(s.asked, string(p.IdentityID)+" "+string(a)+" "+string(r.Kind)+" "+r.ID)
d := s.decisions[0]
if len(s.decisions) > 1 {
s.decisions = s.decisions[1:]
}
return d
}
// ledger records each attempt's outcome by kind.
type ledger struct{ outcomes []string }
func (l *ledger) Sent(context.Context, int64, int, string, time.Duration) error {
l.outcomes = append(l.outcomes, "sent")
return nil
}
func (l *ledger) Failed(_ context.Context, _ int64, _ int, reason string, _ time.Duration) error {
l.outcomes = append(l.outcomes, "failed: "+reason)
return nil
}
func (l *ledger) GaveUp(_ context.Context, _ int64, _ int, reason string, _ time.Duration) error {
l.outcomes = append(l.outcomes, "gave up: "+reason)
return nil
}
// channelLookups counts the sends a worker tried: it has no connector running,
// so a send that was attempted fails and a send that was refused never looks.
type channelLookups struct{ looked int }
func (c *channelLookups) Delivering(string) []*connectors.Connector { return nil }
func (c *channelLookups) Get(string) (*connectors.Connector, bool) {
c.looked++
return nil, false
}
// TestDeliveryIsAuthorizedOnEveryAttempt guards that a queued message is sent
// only while the workload principal may still deliver on its channel. Each
// attempt, including a retry after a backoff or a restart, asks again: a
// revoked grant ends the message as failed, and a chain that can't decide
// leaves it queued for its next attempt instead of dropping it.
func TestDeliveryIsAuthorizedOnEveryAttempt(t *testing.T) {
allowed, revoked, unavailable := governance.Allowed(), governance.DeniedAt(governance.LevelOrg, []string{"org-workload"}), governance.Unavailable()
tests := []struct {
name string
decisions []governance.Decision
unwired bool
attempts int
wantSends int
wantOutcomes []string
}{
{name: "an allowed attempt is sent", decisions: []governance.Decision{allowed}, attempts: 1, wantSends: 1, wantOutcomes: []string{"failed: connector \"slack\" isn't running"}},
{name: "a revoked grant ends the message", decisions: []governance.Decision{revoked}, attempts: 1, wantOutcomes: []string{"gave up: " + connectors.ErrRejected.Error() + ": " + governance.ErrDenied.Error() + ": deliver delivery slack"}},
{name: "a retry after revocation is refused", decisions: []governance.Decision{allowed, revoked}, attempts: 2, wantSends: 1, wantOutcomes: []string{"failed: connector \"slack\" isn't running", "gave up: " + connectors.ErrRejected.Error() + ": " + governance.ErrDenied.Error() + ": deliver delivery slack"}},
{name: "an undecidable chain leaves the message queued", decisions: []governance.Decision{unavailable}, attempts: 3},
{name: "no policy wired leaves the message queued", unwired: true, attempts: 1},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
access, out, channels := &sequencedAccess{decisions: tt.decisions}, &ledger{}, &channelLookups{}
m := &Module{outcomes: out, channels: channels, log: slog.New(slog.DiscardHandler)}
if !tt.unwired {
m.UseAccess(access)
}
for range tt.attempts {
m.deliver(t.Context(), store.Message{Seq: 1, ID: uuid.New(), Channel: "slack", Attempts: 1})
}
if channels.looked != tt.wantSends {
t.Fatalf("sends tried = %d, want %d", channels.looked, tt.wantSends)
}
if !slices.Equal(out.outcomes, tt.wantOutcomes) {
t.Fatalf("outcomes = %q, want %q", out.outcomes, tt.wantOutcomes)
}
for _, call := range access.asked {
if !strings.HasPrefix(call, "workload deliver delivery ") {
t.Fatalf("asked %q, want the workload principal to deliver", call)
}
}
})
}
}
+39 -7
View File
@@ -28,6 +28,7 @@ import (
"github.com/samcharles93/archie-core/internal/platform/hub"
"github.com/samcharles93/archie-core/modules/connectors"
"github.com/samcharles93/archie-core/modules/deliveries/internal/store"
"github.com/samcharles93/archie-core/modules/governance"
)
const (
@@ -111,16 +112,31 @@ type Channels interface {
type Module struct {
orgID string
store *store.Store
outcomes outcomes
access governance.Authorizer
hub *hub.Hub
channels Channels
log *slog.Logger
poll time.Duration
}
// outcomes records how each attempt to deliver a message ended.
type outcomes interface {
Sent(ctx context.Context, seq int64, attempt int, externalID string, took time.Duration) error
Failed(ctx context.Context, seq int64, attempt int, reason string, took time.Duration) error
GaveUp(ctx context.Context, seq int64, attempt int, reason string, took time.Duration) error
}
// UseAccess gives the module the policy chain that decides, each time a
// worker claims a message, whether it may go out. Until it is set nothing is
// delivered.
func (m *Module) UseAccess(a governance.Authorizer) { m.access = a }
// NewModule returns the deliveries module for orgID, announcing new messages
// on h and sending them on every connector in channels that delivers them.
func NewModule(db *sqlx.DB, log *slog.Logger, orgID string, h *hub.Hub, channels Channels) *Module {
return &Module{orgID: orgID, store: store.New(db), hub: h, channels: channels, log: log, poll: time.Second}
st := store.New(db)
return &Module{orgID: orgID, store: st, outcomes: st, hub: h, channels: channels, log: log, poll: time.Second}
}
// Notify delivers n on every channel. Delivering the same key again changes
@@ -231,7 +247,23 @@ func (m *Module) Work(ctx context.Context) {
}
}
// deliver sends a claimed message when the workload principal may still deliver
// on its channel. Each attempt is decided afresh, so a retry after a backoff or
// a restart honours a revocation made meanwhile. A refusal ends the message as
// failed. When the policy chain can't decide, the message stays queued for its
// next attempt.
func (m *Module) deliver(ctx context.Context, msg store.Message) {
err := governance.RequireWorkload(ctx, m.access, governance.ActionDeliver, governance.Resource{
Kind: governance.KindDelivery, ID: msg.Channel,
})
switch {
case errors.Is(err, governance.ErrDenied):
m.recordFailure(ctx, msg, fmt.Errorf("%w: %w", connectors.ErrRejected, err), 0)
return
case err != nil:
m.log.WarnContext(ctx, "delivery waits for access policies", "channel", msg.Channel, "message", msg.ID, "error", err)
return
}
start := time.Now()
external, err := m.sendTo(ctx, msg)
took := time.Since(start)
@@ -240,7 +272,7 @@ func (m *Module) deliver(ctx context.Context, msg store.Message) {
m.recordFailure(ctx, msg, err, took)
return
}
if err := m.store.Sent(ctx, msg.Seq, msg.Attempts, external, took); err != nil {
if err := m.outcomes.Sent(ctx, msg.Seq, msg.Attempts, external, took); err != nil {
m.log.ErrorContext(ctx, "record delivery", "error", err)
}
}
@@ -248,13 +280,13 @@ func (m *Module) deliver(ctx context.Context, msg store.Message) {
// recordFailure records why an attempt failed. It marks the delivery failed
// when the channel rejected it permanently or the retry limit is reached.
func (m *Module) recordFailure(ctx context.Context, msg store.Message, cause error, took time.Duration) {
record := m.store.Failed
record := m.outcomes.Failed
reason := cause.Error()
switch {
case errors.Is(cause, connectors.ErrRejected):
record = m.store.GaveUp
record = m.outcomes.GaveUp
case msg.Attempts >= maxAttempts:
record = m.store.GaveUp
record = m.outcomes.GaveUp
reason = fmt.Sprintf("gave up after %d attempts: %s", msg.Attempts, reason)
}
if err := record(ctx, msg.Seq, msg.Attempts, reason, took); err != nil {
@@ -292,11 +324,11 @@ func backoff(attempts int) time.Duration {
// Register adds the composer API.
func (m *Module) Register(api huma.API) {
tags := []string{"Composer"}
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindDelivery), huma.Operation{
OperationID: "list-composer-messages", Method: http.MethodGet, Path: "/api/composer/messages",
Summary: "List composer messages with their delivery attempts", Tags: tags,
}, m.messages)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindDelivery), huma.Operation{
OperationID: "stream-composer", Method: http.MethodGet, Path: "/api/composer/stream",
Summary: "Stream the seq of each new composer message", Tags: tags,
Responses: map[string]*huma.Response{"200": {
+7 -6
View File
@@ -23,6 +23,7 @@ import (
"github.com/samcharles93/archie-core/internal/platform/httpapi"
"github.com/samcharles93/archie-core/modules/drafts/internal/store"
"github.com/samcharles93/archie-core/modules/events"
"github.com/samcharles93/archie-core/modules/governance"
"github.com/samcharles93/archie-core/modules/judgement"
"github.com/samcharles93/archie-core/modules/runs"
)
@@ -71,27 +72,27 @@ func NewModule(db *sqlx.DB, log *slog.Logger, orgID string, g Groups, w Workflow
// Register adds the draft API.
func (m *Module) Register(api huma.API) {
tags := []string{"Drafts"}
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindDraft), huma.Operation{
OperationID: "list-drafts", Method: http.MethodGet, Path: "/api/drafts",
Summary: "List drafts", Tags: tags,
}, m.list)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionCreate, governance.KindDraft), huma.Operation{
OperationID: "draft-group", Method: http.MethodPost, Path: "/api/groups/{id}/draft",
Summary: "Draft a trigger and workflow for a group of unmatched events", Tags: tags,
}, m.create)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindDraft), huma.Operation{
OperationID: "get-draft", Method: http.MethodGet, Path: "/api/drafts/{id}",
Summary: "Get a draft", Tags: tags,
}, m.get)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindDraft), huma.Operation{
OperationID: "edit-draft", Method: http.MethodPut, Path: "/api/drafts/{id}",
Summary: "Change a draft's name, workflow and policy", Tags: tags,
}, m.edit)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRun, governance.KindWorkflow), huma.Operation{
OperationID: "dry-run-draft", Method: http.MethodPost, Path: "/api/drafts/{id}/dry-run",
Summary: "Replay a stored event against the draft workflow and policy in a dry run", Tags: tags,
}, m.dryRun)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionCreate, governance.KindWorkflow), huma.Operation{
OperationID: "publish-draft", Method: http.MethodPost, Path: "/api/drafts/{id}/publish",
Summary: "Install the draft's workflow, policy and trigger", Tags: tags,
}, m.publish)
+165
View File
@@ -0,0 +1,165 @@
package events
import (
"context"
"errors"
"io"
"log/slog"
"net/http"
"net/http/httptest"
"slices"
"strings"
"testing"
"github.com/google/uuid"
"github.com/samcharles93/archie-core/internal/platform/httpjson"
"github.com/samcharles93/archie-core/modules/connectors"
"github.com/samcharles93/archie-core/modules/events/internal/store"
"github.com/samcharles93/archie-core/modules/governance"
"github.com/samcharles93/archie-core/modules/runs"
)
// deliveryPolicy answers every delivery with one decision and records who
// asked.
type deliveryPolicy struct {
decision governance.Decision
asked []string
}
func (d *deliveryPolicy) AuthorizeDelivery(_ context.Context, org governance.OrgID, source, addr string) governance.Decision {
d.asked = append(d.asked, string(org)+" "+source+" "+addr)
return d.decision
}
// onceInserter stores an event once per source event id, as the table's
// uniqueness constraint does.
type onceInserter struct{ stored map[string]bool }
func (o *onceInserter) Insert(_ context.Context, e store.Event) (bool, error) {
if o.stored[e.SourceEventID] {
return false, nil
}
o.stored[e.SourceEventID] = true
return true, nil
}
type noEcho struct{}
func (noEcho) SentBy(context.Context, string, ...string) (uuid.UUID, bool, error) {
return uuid.Nil, false, nil
}
func (noEcho) Send(context.Context, string, string, string, string) error { return nil }
// TestIntakeAppliesTheDeliveryPolicyBeforeStoring guards the webhook entry
// point: a delivery that passes source verification is still refused when the
// per-source, per-address delivery policy denies it or can't be read, and
// nothing is parsed or stored then. A redelivery of a stored event id is
// counted as a duplicate and stored once, so it can't dispatch again.
func TestIntakeAppliesTheDeliveryPolicyBeforeStoring(t *testing.T) {
const token = "not-a-real-token" //nolint:gosec // fixture bearer token the verifier must accept
denied := governance.DeniedAt(governance.LevelObject, []string{"hook-allowlist"})
tests := []struct {
name string
bearer string
policy governance.Decision
unwired bool
deliveries int
want int
wantBody string
wantStored int
wantAsked []string
}{
{name: "an allowed delivery is stored", bearer: token, policy: governance.Allowed(), deliveries: 1, want: http.StatusAccepted, wantBody: `"stored":1`, wantStored: 1, wantAsked: []string{"org-sys hook 203.0.113.9"}},
{name: "a redelivered event id is counted, not stored again", bearer: token, policy: governance.Allowed(), deliveries: 2, want: http.StatusAccepted, wantBody: `"duplicates":1`, wantStored: 1, wantAsked: []string{"org-sys hook 203.0.113.9", "org-sys hook 203.0.113.9"}},
{name: "a valid token with a denying policy", bearer: token, policy: denied, deliveries: 1, want: http.StatusForbidden, wantAsked: []string{"org-sys hook 203.0.113.9"}},
{name: "a valid token while the chain is unavailable", bearer: token, policy: governance.Unavailable(), deliveries: 1, want: http.StatusServiceUnavailable, wantAsked: []string{"org-sys hook 203.0.113.9"}},
{name: "a valid token with no policy wired", bearer: token, unwired: true, deliveries: 1, want: http.StatusServiceUnavailable},
{name: "a wrong token never reaches the policy", bearer: "other", policy: governance.Allowed(), deliveries: 1, want: http.StatusUnauthorized},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
policy := &deliveryPolicy{decision: tt.policy}
inserter := &onceInserter{stored: map[string]bool{}}
m := &Module{
orgID: "default", log: slog.New(slog.DiscardHandler), inserter: inserter, deliveries: noEcho{},
reader: fakeSources{store.Source{OrgID: "default", Name: "hook", Connector: "c", Verification: store.Token, TokenSHA256: httpjson.TokenHash(token)}},
parse: func(context.Context, string, []byte, map[string]string) ([]connectors.Event, error) {
return []connectors.Event{{Type: "alert", SourceEventID: "evt-1"}}, nil
},
}
if !tt.unwired {
m.UseDeliveryPolicy(policy)
}
var rec *httptest.ResponseRecorder
for range tt.deliveries {
req := httptest.NewRequestWithContext(t.Context(), http.MethodPost, "/hooks/hook", strings.NewReader(`{}`))
req.SetPathValue("source", "hook")
req.RemoteAddr = "203.0.113.9:4711"
req.Header.Set("Authorization", "Bearer "+tt.bearer)
rec = httptest.NewRecorder()
m.intake(rec, req)
}
body, _ := io.ReadAll(rec.Body)
if rec.Code != tt.want || !strings.Contains(string(body), tt.wantBody) {
t.Fatalf("status %d body %s, want %d containing %q", rec.Code, body, tt.want, tt.wantBody)
}
if len(inserter.stored) != tt.wantStored {
t.Fatalf("events stored = %d, want %d", len(inserter.stored), tt.wantStored)
}
if !slices.Equal(policy.asked, tt.wantAsked) {
t.Fatalf("delivery policy asked %v, want %v", policy.asked, tt.wantAsked)
}
})
}
}
// startRecorder is the run starter a trigger calls: it records the principal
// each start carried and answers with a fixed error.
type startRecorder struct {
err error
principals []governance.IdentityID
}
func (s *startRecorder) Start(ctx context.Context, _ runs.StartRequest) (uuid.UUID, error) {
p, _ := governance.PrincipalFromContext(ctx)
s.principals = append(s.principals, p.IdentityID)
return uuid.New(), s.err
}
func (*startRecorder) CheckTrigger(context.Context, string, string) error { return nil }
// TestTriggersStartRunsAsTheWorkload guards that dispatching an event never
// starts a run without a principal: the workload principal acts, a refusal
// skips the trigger for good, and a chain that can't decide fails the dispatch
// so the event stays queued instead of being dropped.
func TestTriggersStartRunsAsTheWorkload(t *testing.T) {
tests := []struct {
name string
err error
wantStarted bool
wantErr error
}{
{name: "an allowed start", wantStarted: true},
{name: "a refused start is final", err: governance.ErrDenied},
{name: "an undecidable start is retried", err: governance.ErrChainUnavailable, wantErr: governance.ErrChainUnavailable},
{name: "another failure is retried", err: errors.New("database down"), wantErr: errors.New("database down")},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
starts := &startRecorder{err: tt.err}
m := &Module{runs: starts, log: slog.New(slog.DiscardHandler)}
_, started, err := m.startRun(t.Context(), store.Event{ID: uuid.New(), OrgID: "default"}, store.Trigger{Name: "t", Workflow: "triage"})
if started != tt.wantStarted {
t.Fatalf("started = %v, want %v", started, tt.wantStarted)
}
if (err == nil) != (tt.wantErr == nil) || (tt.wantErr != nil && !strings.Contains(err.Error(), tt.wantErr.Error())) {
t.Fatalf("error = %v, want %v", err, tt.wantErr)
}
if !slices.Equal(starts.principals, []governance.IdentityID{governance.WorkloadID}) {
t.Fatalf("start acted as %v, want the workload principal", starts.principals)
}
})
}
}
+9 -8
View File
@@ -17,6 +17,7 @@ import (
"github.com/samcharles93/archie-core/internal/platform/httpapi"
"github.com/samcharles93/archie-core/internal/platform/httpjson"
"github.com/samcharles93/archie-core/modules/events/internal/store"
"github.com/samcharles93/archie-core/modules/governance"
"github.com/samcharles93/archie-core/modules/runs"
)
@@ -24,35 +25,35 @@ import (
// and the events themselves.
func (m *Module) Register(api huma.API) {
tags := []string{"Events"}
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindSource), huma.Operation{
OperationID: "list-sources", Method: http.MethodGet, Path: "/api/sources",
Summary: "List sources", Tags: tags,
}, m.sources)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindSource), huma.Operation{
OperationID: "put-source", Method: http.MethodPut, Path: "/api/sources/{name}",
Summary: "Add or update a source, its verification scheme and its token", Tags: tags,
}, m.putSource)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindSource), huma.Operation{
OperationID: "put-source-key-fields", Method: http.MethodPut, Path: "/api/sources/{name}/key-fields",
Summary: "Set the fields a source's events are grouped by", Tags: tags,
}, m.putKeyFields)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindTrigger), huma.Operation{
OperationID: "list-triggers", Method: http.MethodGet, Path: "/api/triggers",
Summary: "List triggers", Tags: tags,
}, m.triggers)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindTrigger), huma.Operation{
OperationID: "put-trigger", Method: http.MethodPut, Path: "/api/triggers/{name}",
Summary: "Add or change a trigger", Tags: tags,
}, m.putTrigger)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindEventIngest), huma.Operation{
OperationID: "list-groups", Method: http.MethodGet, Path: "/api/groups",
Summary: "List groups of unmatched events", Tags: tags,
}, m.groups)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindEventIngest), huma.Operation{
OperationID: "list-events", Method: http.MethodGet, Path: "/api/events",
Summary: "List recent events", Tags: tags,
}, m.recent)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindEventIngest), huma.Operation{
OperationID: "get-event", Method: http.MethodGet, Path: "/api/events/{id}",
Summary: "Get an event with its payload and the runs it started", Tags: tags,
}, m.event)
+93 -18
View File
@@ -16,6 +16,7 @@ import (
"errors"
"fmt"
"log/slog"
"net"
"net/http"
"regexp"
"strings"
@@ -89,6 +90,8 @@ type Module struct {
orgID string
store *store.Store
reader sourceReader
inserter eventInserter
delivery governance.DeliveryAuthorizer
sealer Sealer
parse func(ctx context.Context, connector string, body []byte, headers map[string]string) ([]connectors.Event, error)
connectors Connectors
@@ -103,7 +106,7 @@ type Module struct {
// NewModule returns the events module for orgID.
func NewModule(db *sqlx.DB, log *slog.Logger, orgID string, sealer Sealer, c Connectors, r Runs, a Answers, l Links, d Deliveries) *Module {
st := store.New(db)
m := &Module{orgID: orgID, store: st, reader: st, sealer: sealer, connectors: c, runs: r, answers: a, links: l, deliveries: d, log: log, poll: time.Second}
m := &Module{orgID: orgID, store: st, reader: st, inserter: st, sealer: sealer, connectors: c, runs: r, answers: a, links: l, deliveries: d, log: log, poll: time.Second}
m.parse = m.parseWith
return m
}
@@ -113,15 +116,26 @@ type sourceReader interface {
Source(ctx context.Context, orgID, name string) (store.Source, error)
}
// eventInserter stores an event, and reports false when its source event id
// was stored before.
type eventInserter interface {
Insert(ctx context.Context, e store.Event) (isNew bool, err error)
}
// UseDeliveryPolicy gives intake the policy that decides, per source and
// sender address, who may deliver. Until it is set every delivery is refused.
func (m *Module) UseDeliveryPolicy(d governance.DeliveryAuthorizer) { m.delivery = d }
// Routes adds the webhook intake. It stays outside the API because each
// source verifies its own deliveries.
func (m *Module) Routes(mux *http.ServeMux) {
mux.HandleFunc("POST /hooks/{source}", m.intake)
}
// intake verifies a delivery, parses it with the source's connector and stores
// each event before responding. A redelivered event violates a uniqueness
// constraint and is counted as a duplicate.
// intake verifies a delivery, checks the source's delivery policy, parses it
// with the source's connector and stores each event before responding. A
// redelivered event violates a uniqueness constraint, is counted as a
// duplicate and is not dispatched again.
func (m *Module) intake(w http.ResponseWriter, r *http.Request) {
src, parsed, body, status, err := m.accept(r)
if err != nil {
@@ -170,6 +184,9 @@ func (m *Module) accept(r *http.Request) (src store.Source, parsed []connectors.
return m.refuse(ctx, src, err)
}
}
if status, err := m.deliveryAllowed(ctx, src, r); err != nil {
return src, nil, nil, status, err
}
parsed, err = m.parse(ctx, src.Connector, body, map[string]string{"Content-Type": r.Header.Get("Content-Type")})
if errors.Is(err, errConnectorDown) {
return src, nil, nil, http.StatusServiceUnavailable, err
@@ -195,6 +212,36 @@ func (m *Module) refuse(ctx context.Context, src store.Source, err error) (store
return src, nil, nil, http.StatusServiceUnavailable, errors.New("couldn't verify the delivery")
}
var (
errDeliveryDenied = errors.New("delivery not permitted")
errDeliveryUnavailable = errors.New("delivery policy unavailable")
)
// deliveryAllowed applies the source's delivery policy to the sender's address.
// A verified delivery still needs it. When the policy chain can't decide the
// delivery is refused with 503, so the sender retries and nothing is stored.
func (m *Module) deliveryAllowed(ctx context.Context, src store.Source, r *http.Request) (int, error) {
if m.delivery == nil {
return http.StatusServiceUnavailable, errDeliveryUnavailable
}
addr, _, err := net.SplitHostPort(r.RemoteAddr)
if err != nil {
addr = r.RemoteAddr
}
// Delivery policies belong to the operating organisation, whatever the
// source's own org id says.
d := m.delivery.AuthorizeDelivery(ctx, governance.DefaultOrgID, src.Name, addr)
switch {
case d.Allowed:
return 0, nil
case errors.Is(d.Err, governance.ErrChainUnavailable):
m.log.WarnContext(ctx, "delivery policy unavailable", "source", src.Name)
return http.StatusServiceUnavailable, errDeliveryUnavailable
}
m.log.WarnContext(ctx, "refused webhook delivery", "source", src.Name, "reason", "delivery policy", "level", d.Level, "policies", d.Policies)
return http.StatusForbidden, errDeliveryDenied
}
// parseWith has a running connector parse a delivery.
func (m *Module) parseWith(ctx context.Context, connector string, body []byte, headers map[string]string) ([]connectors.Event, error) {
conn, ok := m.connectors.Get(connector)
@@ -212,7 +259,7 @@ func (m *Module) save(ctx context.Context, src store.Source, parsed []connectors
if err != nil {
return stored, duplicates, fmt.Errorf("check delivery provenance: %w", err)
}
isNew, err := m.store.Insert(ctx, newRow(m.orgID, src, e, body, own, run))
isNew, err := m.inserter.Insert(ctx, newRow(m.orgID, src, e, body, own, run))
if err != nil {
return stored, duplicates, err
}
@@ -434,7 +481,7 @@ func (m *Module) dispatch(tx *sqlx.Tx, e store.Event) (bool, error) {
if err != nil {
return false, err
}
matched := false
matched, refused := false, false
for _, t := range triggers {
var filter map[string]string
if err := json.Unmarshal(t.Filter, &filter); err != nil {
@@ -443,11 +490,13 @@ func (m *Module) dispatch(tx *sqlx.Tx, e store.Event) (bool, error) {
if !match.Fields(e.Fields, filter) {
continue
}
runID, err := m.runs.Start(ctx, runs.StartRequest{
OrgID: e.OrgID, Workflow: t.Workflow, Key: e.ID.String() + ":" + t.Name, Input: runInput(e),
})
runID, started, err := m.startRun(ctx, e, t)
if err != nil {
return false, fmt.Errorf("start run for trigger %q: %w", t.Name, err)
return false, err
}
if !started {
refused = true
continue
}
if err := store.RecordDispatch(ctx, tx, e.ID, t.Name, runID); err != nil {
return false, err
@@ -455,18 +504,44 @@ func (m *Module) dispatch(tx *sqlx.Tx, e store.Event) (bool, error) {
m.log.InfoContext(ctx, "trigger started run", "event", e.ID, "trigger", t.Name, "run", runID)
matched = true
}
if !matched {
created, err := store.NoteUnmatched(ctx, tx, e)
if err != nil {
return false, err
}
if created {
m.log.InfoContext(ctx, "unmatched events started a group", "source", e.Source, "type", e.Type)
}
if !matched && !refused {
return false, m.noteUnmatched(ctx, tx, e)
}
return matched, nil
}
// noteUnmatched files an event no trigger took into a group for review.
func (m *Module) noteUnmatched(ctx context.Context, tx *sqlx.Tx, e store.Event) error {
created, err := store.NoteUnmatched(ctx, tx, e)
if err != nil {
return err
}
if created {
m.log.InfoContext(ctx, "unmatched events started a group", "source", e.Source, "type", e.Type)
}
return nil
}
// startRun starts the run trigger t asks for, as the workload principal, so
// the start is decided by the same policy chain as any other caller. A refusal
// is final: it reports no run and no error, and the trigger is skipped. A policy
// chain that can't decide returns an error instead, which rolls the dispatch
// back so the event stays queued and is dispatched again.
func (m *Module) startRun(ctx context.Context, e store.Event, t store.Trigger) (runID uuid.UUID, started bool, err error) {
ctx = governance.WithPrincipal(ctx, governance.WorkloadPrincipal(governance.DefaultOrgID))
runID, err = m.runs.Start(ctx, runs.StartRequest{
OrgID: e.OrgID, Workflow: t.Workflow, Key: e.ID.String() + ":" + t.Name, Input: runInput(e),
})
if errors.Is(err, governance.ErrDenied) {
m.log.WarnContext(ctx, "trigger not permitted to start its workflow", "event", e.ID, "trigger", t.Name, "error", err)
return uuid.Nil, false, nil
}
if err != nil {
return uuid.Nil, false, fmt.Errorf("start run for trigger %q: %w", t.Name, err)
}
return runID, true, nil
}
// Origin returns the event and trigger that started a run.
func (m *Module) Origin(ctx context.Context, runID uuid.UUID) (runs.Origin, bool, error) {
o, ok, err := m.store.OriginOf(ctx, m.orgID, runID)
+1 -1
View File
@@ -50,7 +50,7 @@ func (m *Module) tick(ctx context.Context, now time.Time) error {
if err != nil {
return fmt.Errorf("encode tick: %w", err)
}
isNew, err := m.store.Insert(ctx, tickEvent(m.orgID, t.Name, slot, fields))
isNew, err := m.inserter.Insert(ctx, tickEvent(m.orgID, t.Name, slot, fields))
if err != nil {
return err
}
+9 -1
View File
@@ -16,6 +16,7 @@ import (
"github.com/samcharles93/archie-core/internal/platform/seal"
"github.com/samcharles93/archie-core/modules/connectors"
"github.com/samcharles93/archie-core/modules/events/internal/store"
"github.com/samcharles93/archie-core/modules/governance"
)
type fakeSources struct{ src store.Source }
@@ -71,7 +72,7 @@ func TestHMACSourceVerifiesBeforeParsing(t *testing.T) {
t.Run(tt.name, func(t *testing.T) {
parsed := false
m := &Module{
orgID: "org", reader: fakeSources{src}, sealer: sealer,
orgID: "org", reader: fakeSources{src}, sealer: sealer, delivery: permitAll{},
log: slog.New(slog.DiscardHandler),
parse: func(context.Context, string, []byte, map[string]string) ([]connectors.Event, error) {
parsed = true
@@ -93,3 +94,10 @@ func TestHMACSourceVerifiesBeforeParsing(t *testing.T) {
})
}
}
// permitAll accepts a delivery from any address.
type permitAll struct{}
func (permitAll) AuthorizeDelivery(context.Context, governance.OrgID, string, string) governance.Decision {
return governance.Allowed()
}
+3
View File
@@ -107,6 +107,9 @@ const (
KindMemory ResourceKind = "memory"
KindSettings ResourceKind = "settings"
KindInstance ResourceKind = "instance"
KindAccount ResourceKind = "account"
KindChatSession ResourceKind = "chat_session"
KindNote ResourceKind = "note"
)
// Policy is one stored Cedar policy.
+19 -6
View File
@@ -449,17 +449,24 @@ type fakePolicySeed struct {
ids []string
rows []store.PolicyRow
err error
// later holds the policy IDs of every seed after the first.
later []string
}
func (f *fakePolicySeed) SeedOrgPolicies(_ context.Context, _ string, shippedIDs []string, rows []store.PolicyRow) error {
f.calls++
f.ids, f.rows = shippedIDs, rows
if f.calls == 1 {
f.ids, f.rows = shippedIDs, rows
} else {
f.later = append(f.later, shippedIDs...)
}
return f.err
}
// TestSeedShippedPolicies guards that the shipped set is written in one call
// TestSeedShippedPolicies guards that the role policies are written in one call
// rather than one policy at a time, which is what left an org holding only some
// of its role policies. The transaction, the zero-count check under the lock and
// of them, and that each later shipped policy is seeded on its own so an org
// seeded before it existed still receives it. The transaction, the zero-count check under the lock and
// how deletions and edits survive are proven against Postgres in the binary's
// smoke test.
func TestSeedShippedPolicies(t *testing.T) {
@@ -467,9 +474,15 @@ func TestSeedShippedPolicies(t *testing.T) {
if err := seedShippedPolicies(t.Context(), seeder, DefaultOrgID); err != nil {
t.Fatalf("seed: %v", err)
}
shipped := ShippedOrgPolicies(DefaultOrgID)
if seeder.calls != 1 {
t.Fatalf("seed calls = %d, want 1", seeder.calls)
shipped := ShippedRolePolicies(DefaultOrgID)
extras := shippedExtraPolicies(DefaultOrgID)
if seeder.calls != 1+len(extras) {
t.Fatalf("seed calls = %d, want the role policies in one call and %d more", seeder.calls, len(extras))
}
for i, p := range extras {
if seeder.later[i] != p.ID {
t.Fatalf("later seed %d = %s, want %s", i, seeder.later[i], p.ID)
}
}
if len(seeder.rows) != len(shipped) || len(seeder.ids) != len(shipped) {
t.Fatalf("seeded %d rows and %d ids, want %d of each", len(seeder.rows), len(seeder.ids), len(shipped))
+24 -30
View File
@@ -88,40 +88,34 @@ type userReply struct {
// authentication settings and what the dashboard can show.
func (m *Module) RegisterAccounts(api huma.API) {
tags := []string{"Accounts"}
public := func(id, method, path, summary string, status int) huma.Operation {
return httpapi.Public(huma.Operation{OperationID: id, Method: method, Path: path, Summary: summary, Tags: tags, DefaultStatus: status})
}
signedIn := func(id, method, path, summary string, status int) huma.Operation {
return httpapi.SignedIn(huma.Operation{OperationID: id, Method: method, Path: path, Summary: summary, Tags: tags, DefaultStatus: status})
}
admin := func(id, method, path, summary string, status int) huma.Operation {
op := func(id, method, path, summary string, status int) huma.Operation {
return huma.Operation{OperationID: id, Method: method, Path: path, Summary: summary, Tags: tags, DefaultStatus: status}
}
huma.Register(api, public("get-auth-status", http.MethodGet, "/api/auth/status", "Report setup and who is signed in", 0), m.authStatus)
huma.Register(api, public("set-up-account", http.MethodPost, "/api/auth/setup", "Create the instance owner and sign in", 0), m.setUpAccount)
huma.Register(api, public("sign-in", http.MethodPost, "/api/auth/login", "Sign in with email and password", 0), m.signIn)
huma.Register(api, public("sign-out", http.MethodPost, "/api/auth/logout", "Sign out", http.StatusNoContent), m.signOut)
huma.Register(api, public("recover-account", http.MethodPost, "/api/auth/recover", "Reset a password with a recovery code", http.StatusNoContent), m.recoverAccount)
huma.Register(api, public("begin-passkey-sign-in", http.MethodPost, "/api/auth/passkey/begin", "Start signing in with a passkey", 0), m.beginPasskeySignIn)
huma.Register(api, public("finish-passkey-sign-in", http.MethodPost, "/api/auth/passkey/finish", "Finish signing in with a passkey", 0), m.finishPasskeySignIn)
huma.Register(api, public("begin-oidc-sign-in", http.MethodGet, "/oauth2/login", "Send the browser to the identity provider", http.StatusSeeOther), m.beginOIDC)
huma.Register(api, public("finish-oidc-sign-in", http.MethodGet, oidcCallbackPath, "Complete the identity provider's sign-in", http.StatusSeeOther), m.finishOIDC)
httpapi.Register(api, httpapi.Public(), op("get-auth-status", http.MethodGet, "/api/auth/status", "Report setup and who is signed in", 0), m.authStatus)
httpapi.Register(api, httpapi.Public(), op("set-up-account", http.MethodPost, "/api/auth/setup", "Create the instance owner and sign in", 0), m.setUpAccount)
httpapi.Register(api, httpapi.Public(), op("sign-in", http.MethodPost, "/api/auth/login", "Sign in with email and password", 0), m.signIn)
httpapi.Register(api, httpapi.Public(), op("sign-out", http.MethodPost, "/api/auth/logout", "Sign out", http.StatusNoContent), m.signOut)
httpapi.Register(api, httpapi.Public(), op("recover-account", http.MethodPost, "/api/auth/recover", "Reset a password with a recovery code", http.StatusNoContent), m.recoverAccount)
httpapi.Register(api, httpapi.Public(), op("begin-passkey-sign-in", http.MethodPost, "/api/auth/passkey/begin", "Start signing in with a passkey", 0), m.beginPasskeySignIn)
httpapi.Register(api, httpapi.Public(), op("finish-passkey-sign-in", http.MethodPost, "/api/auth/passkey/finish", "Finish signing in with a passkey", 0), m.finishPasskeySignIn)
httpapi.Register(api, httpapi.Public(), op("begin-oidc-sign-in", http.MethodGet, "/oauth2/login", "Send the browser to the identity provider", http.StatusSeeOther), m.beginOIDC)
httpapi.Register(api, httpapi.Public(), op("finish-oidc-sign-in", http.MethodGet, oidcCallbackPath, "Complete the identity provider's sign-in", http.StatusSeeOther), m.finishOIDC)
huma.Register(api, signedIn("change-password", http.MethodPost, "/api/account/password", "Change your password", http.StatusNoContent), m.changePassword)
huma.Register(api, signedIn("create-recovery-code", http.MethodPost, "/api/account/recovery", "Create a recovery code", 0), m.createRecoveryCode)
huma.Register(api, signedIn("list-passkeys", http.MethodGet, "/api/account/passkeys", "List your passkeys", 0), m.listPasskeys)
huma.Register(api, signedIn("begin-passkey-registration", http.MethodPost, "/api/account/passkeys/begin", "Start adding a passkey", 0), m.beginPasskeyRegistration)
huma.Register(api, signedIn("finish-passkey-registration", http.MethodPost, "/api/account/passkeys/finish", "Finish adding a passkey", 0), m.finishPasskeyRegistration)
huma.Register(api, signedIn("delete-passkey", http.MethodDelete, "/api/account/passkeys/{id}", "Remove a passkey", http.StatusNoContent), m.deletePasskey)
huma.Register(api, signedIn("list-personal-tokens", http.MethodGet, "/api/tokens", "List your personal API tokens", 0), m.listTokens)
huma.Register(api, signedIn("create-personal-token", http.MethodPost, "/api/tokens", "Create a personal API token", http.StatusCreated), m.createToken)
huma.Register(api, signedIn("revoke-personal-token", http.MethodDelete, "/api/tokens/{id}", "Revoke a personal API token", http.StatusNoContent), m.revokeToken)
m.registerLinks(api, signedIn)
huma.Register(api, signedIn("get-capabilities", http.MethodGet, "/api/capabilities", "Report which dashboard sections this binary serves", 0), m.capabilities)
httpapi.Register(api, httpapi.Authorized(ActionUpdate, KindAccount), op("change-password", http.MethodPost, "/api/account/password", "Change your password", http.StatusNoContent), m.changePassword)
httpapi.Register(api, httpapi.Authorized(ActionCreate, KindAccount), op("create-recovery-code", http.MethodPost, "/api/account/recovery", "Create a recovery code", 0), m.createRecoveryCode)
httpapi.Register(api, httpapi.Authorized(ActionRead, KindAccount), op("list-passkeys", http.MethodGet, "/api/account/passkeys", "List your passkeys", 0), m.listPasskeys)
httpapi.Register(api, httpapi.Authorized(ActionCreate, KindAccount), op("begin-passkey-registration", http.MethodPost, "/api/account/passkeys/begin", "Start adding a passkey", 0), m.beginPasskeyRegistration)
httpapi.Register(api, httpapi.Authorized(ActionCreate, KindAccount), op("finish-passkey-registration", http.MethodPost, "/api/account/passkeys/finish", "Finish adding a passkey", 0), m.finishPasskeyRegistration)
httpapi.Register(api, httpapi.Authorized(ActionDelete, KindAccount), op("delete-passkey", http.MethodDelete, "/api/account/passkeys/{id}", "Remove a passkey", http.StatusNoContent), m.deletePasskey)
httpapi.Register(api, httpapi.Authorized(ActionRead, KindAccount), op("list-personal-tokens", http.MethodGet, "/api/tokens", "List your personal API tokens", 0), m.listTokens)
httpapi.Register(api, httpapi.Authorized(ActionCreate, KindAccount), op("create-personal-token", http.MethodPost, "/api/tokens", "Create a personal API token", http.StatusCreated), m.createToken)
httpapi.Register(api, httpapi.Authorized(ActionDelete, KindAccount), op("revoke-personal-token", http.MethodDelete, "/api/tokens/{id}", "Revoke a personal API token", http.StatusNoContent), m.revokeToken)
m.registerLinks(api, op)
httpapi.Register(api, httpapi.Authorized(ActionRead, KindAccount), op("get-capabilities", http.MethodGet, "/api/capabilities", "Report which dashboard sections this binary serves", 0), m.capabilities)
huma.Register(api, admin("create-account", http.MethodPost, "/api/accounts", "Create an account", http.StatusCreated), m.createAccount)
huma.Register(api, admin("get-authentication", http.MethodGet, "/api/authentication", "Get the authentication settings", 0), m.getAuthentication)
huma.Register(api, admin("put-authentication", http.MethodPut, "/api/authentication", "Change the authentication settings", http.StatusNoContent), m.putAuthentication)
httpapi.Register(api, httpapi.AdminAuthorized(ActionManageIdentities, KindIdentity), op("create-account", http.MethodPost, "/api/accounts", "Create an account", http.StatusCreated), m.createAccount)
httpapi.Register(api, httpapi.AdminAuthorized(ActionRead, KindSettings), op("get-authentication", http.MethodGet, "/api/authentication", "Get the authentication settings", 0), m.getAuthentication)
httpapi.Register(api, httpapi.AdminAuthorized(ActionUpdate, KindSettings), op("put-authentication", http.MethodPut, "/api/authentication", "Change the authentication settings", http.StatusNoContent), m.putAuthentication)
}
// accountError turns an account failure into the status a person can act on.
+99
View File
@@ -0,0 +1,99 @@
package governance
import (
"context"
"errors"
"fmt"
"log/slog"
"time"
"github.com/samcharles93/archie-core/internal/platform/httpapi"
)
// ErrDenied is returned when the policy chain refuses an action.
var ErrDenied = errors.New("access: not permitted")
// WorkloadID is the identity background work acts as.
const WorkloadID IdentityID = "workload"
// WorkloadPrincipal returns the principal queued work acts as in org: trigger
// dispatch, run workers and delivery workers. It holds only the workload role,
// which the shipped workload policy grants a narrow set of actions, so
// background work is decided by the same chain as any other caller.
func WorkloadPrincipal(org OrgID) Principal {
return Principal{
IdentityID: WorkloadID,
Kind: KindSystem,
Org: org,
Memberships: []Membership{{IdentityID: WorkloadID, OrgID: org, Role: RoleWorkload}},
}
}
// Require asks a whether p may take action on r. It returns nil when allowed,
// ErrChainUnavailable when a cannot decide, and an error wrapping ErrDenied
// otherwise. A nil a cannot decide, so the action is refused.
func Require(ctx context.Context, a Authorizer, p Principal, action Action, r Resource) error {
if a == nil {
return ErrChainUnavailable
}
d := a.Authorize(ctx, p, action, r, AccessContext{Time: time.Now()})
switch {
case d.Allowed:
return nil
case errors.Is(d.Err, ErrChainUnavailable):
return ErrChainUnavailable
}
return fmt.Errorf("%w: %s %s %s", ErrDenied, action, r.Kind, r.ID)
}
// RequireWorkload is Require for the workload principal of the operating
// organisation, whose policies govern the work every module queues.
func RequireWorkload(ctx context.Context, a Authorizer, action Action, r Resource) error {
r.Org = DefaultOrgID
return Require(ctx, a, WorkloadPrincipal(DefaultOrgID), action, r)
}
type recording struct {
Authorizer
denials DenialRecorder
log *slog.Logger
}
// Recording wraps a so every refusal is stored as a denial, whichever entry
// point asked. A decision that could not be made is not a denial and is not
// stored.
func Recording(a Authorizer, denials DenialRecorder, log *slog.Logger) Authorizer {
return recording{Authorizer: a, denials: denials, log: log}
}
func (r recording) Authorize(ctx context.Context, p Principal, action Action, res Resource, c AccessContext) Decision {
d := r.Authorizer.Authorize(ctx, p, action, res, c)
if d.Allowed || errors.Is(d.Err, ErrChainUnavailable) {
return d
}
err := r.denials.RecordDenial(context.WithoutCancel(ctx), Denial{
Principal: p.IdentityID, Org: p.Org, Action: action, Kind: res.Kind, ResourceID: res.ID,
Level: d.Level, Policies: d.Policies, At: time.Now(), Count: 1,
})
if err != nil {
r.log.ErrorContext(ctx, "record access denial", "principal", p.IdentityID, "action", action, "kind", res.Kind, "error", err)
}
return d
}
// Allow decides a request for the HTTP API's guard: the caller acting in ctx
// against the live policy chain.
func (m *Module) Allow(ctx context.Context, action, kind string) error {
p, ok := PrincipalFromContext(ctx)
if !ok {
return httpapi.ErrDenied
}
err := Require(ctx, m.authz(), p, Action(action), Resource{Kind: ResourceKind(kind), Org: p.Org})
switch {
case err == nil:
return nil
case errors.Is(err, ErrDenied):
return httpapi.ErrDenied
}
return httpapi.ErrUnavailable
}
+111
View File
@@ -0,0 +1,111 @@
package governance
import (
"context"
"errors"
"log/slog"
"testing"
"github.com/samcharles93/archie-core/internal/platform/httpapi"
)
// TestShippedPoliciesLetTheWorkloadWork guards that a fresh install runs its
// workflows: the workload principal may run workflows, deliver messages and
// read, and may do nothing that changes configuration or reads secrets. Members
// reach their own account, conversations and notes whatever their role.
func TestShippedPoliciesLetTheWorkloadWork(t *testing.T) {
engine := NewEngine(ShippedOrgPolicies(DefaultOrgID))
member := func(role Role) Principal {
return Principal{IdentityID: "alice", Org: DefaultOrgID, Memberships: []Membership{{IdentityID: "alice", OrgID: DefaultOrgID, Role: role}}}
}
tests := []struct {
name string
who Principal
action Action
kind ResourceKind
want bool
}{
{"workload runs a workflow", WorkloadPrincipal(DefaultOrgID), ActionRun, KindWorkflow, true},
{"workload delivers", WorkloadPrincipal(DefaultOrgID), ActionDeliver, KindDelivery, true},
{"workload reads", WorkloadPrincipal(DefaultOrgID), ActionRead, KindRun, true},
{"workload does not change a workflow", WorkloadPrincipal(DefaultOrgID), ActionUpdate, KindWorkflow, false},
{"workload does not read secrets", WorkloadPrincipal(DefaultOrgID), ActionReadSecret, KindSecret, false},
{"workload does not manage policies", WorkloadPrincipal(DefaultOrgID), ActionManagePolicies, KindPolicy, false},
{"a viewer changes their account", member(RoleViewer), ActionUpdate, KindAccount, true},
{"a viewer sends a chat turn", member(RoleViewer), ActionCreate, KindChatSession, true},
{"a viewer keeps a note", member(RoleViewer), ActionCreate, KindNote, true},
{"a viewer does not update a workflow", member(RoleViewer), ActionUpdate, KindWorkflow, false},
{"a viewer does not publish a shared note", member(RoleViewer), ActionCreate, KindMemory, false},
{"a developer runs a workflow", member(RoleDeveloper), ActionRun, KindWorkflow, true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
err := Require(t.Context(), engine, tt.who, tt.action, Resource{Kind: tt.kind, Org: tt.who.Org})
if (err == nil) != tt.want {
t.Fatalf("Require = %v, want allowed %v", err, tt.want)
}
if err != nil && !errors.Is(err, ErrDenied) {
t.Fatalf("a refusal is %v, want %v", err, ErrDenied)
}
})
}
}
type denialLog struct{ recorded []Denial }
func (d *denialLog) RecordDenial(_ context.Context, denial Denial) error {
d.recorded = append(d.recorded, denial)
return nil
}
// TestEnforcementFailsClosedAndRecordsRefusals guards the single seam every
// entry point shares: a chain that is not loaded refuses with
// ErrChainUnavailable, as does one with no authorizer at all, a refusal is
// recorded as a denial, and an undecidable request is not.
func TestEnforcementFailsClosedAndRecordsRefusals(t *testing.T) {
failing := func(context.Context) (int64, error) { return 0, errors.New("database down") }
nothing := func(context.Context) ([]Policy, error) { return nil, nil }
pending := NewPending(failing, nothing, slog.New(slog.DiscardHandler))
loaded := NewEngine(ShippedOrgPolicies(DefaultOrgID))
admin := SharedTokenOwner()
viewer := Principal{IdentityID: "bob", Org: DefaultOrgID, Memberships: []Membership{{IdentityID: "bob", OrgID: DefaultOrgID, Role: RoleViewer}}}
resource := Resource{Kind: KindWorkflow, ID: "triage", Org: DefaultOrgID}
tests := []struct {
name string
authorizer Authorizer
who Principal
wantErr error
wantDenials int
wantHTTPDeny error
}{
{name: "a chain that is not loaded", authorizer: pending, who: admin, wantErr: ErrChainUnavailable, wantHTTPDeny: httpapi.ErrUnavailable},
{name: "no authorizer", authorizer: nil, who: admin, wantErr: ErrChainUnavailable, wantHTTPDeny: httpapi.ErrUnavailable},
{name: "a refusal", authorizer: loaded, who: viewer, wantErr: ErrDenied, wantDenials: 1, wantHTTPDeny: httpapi.ErrDenied},
{name: "a grant", authorizer: loaded, who: admin},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
denials := &denialLog{}
var a Authorizer
if tt.authorizer != nil {
a = Recording(tt.authorizer, denials, slog.New(slog.DiscardHandler))
}
if err := Require(t.Context(), a, tt.who, ActionRun, resource); !errors.Is(err, tt.wantErr) {
t.Fatalf("Require = %v, want %v", err, tt.wantErr)
}
if len(denials.recorded) != tt.wantDenials {
t.Fatalf("denials recorded = %d, want %d", len(denials.recorded), tt.wantDenials)
}
m := &Module{}
if a != nil {
m.UseAuthorizer(a)
}
ctx := WithPrincipal(t.Context(), tt.who)
if err := m.Allow(ctx, string(ActionRun), string(KindWorkflow)); !errors.Is(err, tt.wantHTTPDeny) {
t.Fatalf("Allow = %v, want %v", err, tt.wantHTTPDeny)
}
})
}
}
+18 -9
View File
@@ -15,6 +15,7 @@ import (
"net/url"
"regexp"
"strings"
"sync/atomic"
"time"
"github.com/danielgtaylor/huma/v2"
@@ -255,7 +256,7 @@ type Module struct {
store *store.Store
log *slog.Logger
credentials Credentials
authorizer Authorizer
authorizer atomic.Pointer[Authorizer]
oidc *oidcLogin
setup *SetupSignal
channels ChannelLinks
@@ -273,7 +274,15 @@ func (m *Module) UseCredentials(c Credentials) { m.credentials = c }
// UseAuthorizer gives the module the live policy chain that administrative
// writes are checked against.
func (m *Module) UseAuthorizer(a Authorizer) { m.authorizer = a }
func (m *Module) UseAuthorizer(a Authorizer) { m.authorizer.Store(&a) }
// authz returns the policy chain, or nil before UseAuthorizer.
func (m *Module) authz() Authorizer {
if a := m.authorizer.Load(); a != nil {
return *a
}
return nil
}
// AgentModel returns the organisation's agent model.
func (m *Module) AgentModel(ctx context.Context) (Model, error) {
@@ -388,31 +397,31 @@ func (m *Module) ApprovalDeadline(ctx context.Context) (time.Duration, error) {
// Register adds the settings API: organisation settings and the agent model.
func (m *Module) Register(api huma.API) {
tags := []string{"Governance"}
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(ActionRead, KindSettings), huma.Operation{
OperationID: "get-settings", Method: http.MethodGet, Path: "/api/settings",
Summary: "Get the organisation settings", Tags: tags,
}, m.getSettings)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(ActionUpdate, KindSettings), huma.Operation{
OperationID: "put-settings", Method: http.MethodPut, Path: "/api/settings",
Summary: "Change the organisation settings", Tags: tags,
}, m.putSettings)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(ActionRead, KindSettings), huma.Operation{
OperationID: "list-agent-models", Method: http.MethodGet, Path: "/api/settings/agent-models",
Summary: "List agent models by alias", Tags: tags,
}, m.listAgentModels)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(ActionRead, KindSettings), huma.Operation{
OperationID: "get-agent-model", Method: http.MethodGet, Path: "/api/settings/agent-model",
Summary: "Get the agent model", Tags: tags,
}, m.getAgentModel)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(ActionUpdate, KindSettings), huma.Operation{
OperationID: "put-agent-model", Method: http.MethodPut, Path: "/api/settings/agent-model",
Summary: "Set the agent model", Tags: tags,
}, m.putAgentModel)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(ActionUpdate, KindSettings), huma.Operation{
OperationID: "delete-agent-model", Method: http.MethodDelete, Path: "/api/settings/agent-model",
Summary: "Delete an agent model", Tags: tags, DefaultStatus: http.StatusNoContent,
}, m.deleteAgentModel)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(ActionUpdate, KindSettings), huma.Operation{
OperationID: "test-agent-model", Method: http.MethodPost, Path: "/api/settings/agent-model/test",
Summary: "Ask a model one question before saving it", Tags: tags,
}, m.testAgentModel)
+4 -4
View File
@@ -245,10 +245,10 @@ func (m *Module) linkError(ctx context.Context, err error) error {
return m.accountError(ctx, err)
}
func (m *Module) registerLinks(api huma.API, signedIn func(id, method, path, summary string, status int) huma.Operation) {
huma.Register(api, signedIn("list-channel-links", http.MethodGet, "/api/account/channels", "List the channels you can link and your linked accounts", 0), m.listChannels)
huma.Register(api, signedIn("begin-channel-link", http.MethodPost, "/api/account/channels/{connector}/link", "Start linking a channel account", 0), m.beginChannelLink)
huma.Register(api, signedIn("unlink-channel", http.MethodDelete, "/api/account/channels/{connector}/{subject}", "Unlink a channel account", http.StatusNoContent), m.unlinkChannel)
func (m *Module) registerLinks(api huma.API, op func(id, method, path, summary string, status int) huma.Operation) {
httpapi.Register(api, httpapi.Authorized(ActionRead, KindAccount), op("list-channel-links", http.MethodGet, "/api/account/channels", "List the channels you can link and your linked accounts", 0), m.listChannels)
httpapi.Register(api, httpapi.Authorized(ActionUpdate, KindAccount), op("begin-channel-link", http.MethodPost, "/api/account/channels/{connector}/link", "Start linking a channel account", 0), m.beginChannelLink)
httpapi.Register(api, httpapi.Authorized(ActionUpdate, KindAccount), op("unlink-channel", http.MethodDelete, "/api/account/channels/{connector}/{subject}", "Unlink a channel account", http.StatusNoContent), m.unlinkChannel)
}
// AccountOf returns the id of the account that holds identity, written as
+3
View File
@@ -72,6 +72,9 @@ const (
RoleAdmin Role = "admin"
RoleDeveloper Role = "developer"
RoleViewer Role = "viewer"
// RoleWorkload is the role of the principal background work acts as. No
// member holds it.
RoleWorkload Role = "workload"
)
// Validate reports whether r is a valid role identifier.
+12 -12
View File
@@ -88,19 +88,19 @@ type listEventsInput struct {
// organisation the caller's request acts in.
func (m *Module) RegisterOrganisations(api huma.API) {
tags := []string{"Organisations"}
signedIn := func(id, method, path, summary string, status int) huma.Operation {
return httpapi.SignedIn(huma.Operation{
op := func(id, method, path, summary string, status int) huma.Operation {
return huma.Operation{
OperationID: id, Method: method, Path: path, Summary: summary,
Tags: tags, DefaultStatus: status, MaxBodyBytes: 16 << 10,
})
}
}
huma.Register(api, signedIn("list-orgs", http.MethodGet, "/api/orgs", "List the organisation the caller acts in", 0), m.listOrgs)
huma.Register(api, signedIn("get-org", http.MethodGet, "/api/orgs/{id}", "Get an organisation", 0), m.getOrg)
huma.Register(api, signedIn("rename-org", http.MethodPatch, "/api/orgs/{id}", "Rename an organisation", 0), m.renameOrg)
huma.Register(api, signedIn("list-org-workspaces", http.MethodGet, "/api/orgs/{id}/workspaces", "List an organisation's workspaces", 0), m.listOrgWorkspaces)
huma.Register(api, signedIn("create-org-workspace", http.MethodPost, "/api/orgs/{id}/workspaces", "Create a workspace", http.StatusCreated), m.createOrgWorkspace)
huma.Register(api, signedIn("rename-org-workspace", http.MethodPatch, "/api/orgs/{id}/workspaces/{workspace}", "Rename a workspace", 0), m.renameOrgWorkspace)
huma.Register(api, signedIn("list-org-events", http.MethodGet, "/api/orgs/{id}/history", "List the organisation's name changes", 0), m.listOrgEvents)
httpapi.Register(api, httpapi.Authorized(ActionRead, KindOrg), op("list-orgs", http.MethodGet, "/api/orgs", "List the organisation the caller acts in", 0), m.listOrgs)
httpapi.Register(api, httpapi.Authorized(ActionRead, KindOrg), op("get-org", http.MethodGet, "/api/orgs/{id}", "Get an organisation", 0), m.getOrg)
httpapi.Register(api, httpapi.Authorized(ActionUpdate, KindOrg), op("rename-org", http.MethodPatch, "/api/orgs/{id}", "Rename an organisation", 0), m.renameOrg)
httpapi.Register(api, httpapi.Authorized(ActionRead, KindWorkspace), op("list-org-workspaces", http.MethodGet, "/api/orgs/{id}/workspaces", "List an organisation's workspaces", 0), m.listOrgWorkspaces)
httpapi.Register(api, httpapi.Authorized(ActionCreate, KindWorkspace), op("create-org-workspace", http.MethodPost, "/api/orgs/{id}/workspaces", "Create a workspace", http.StatusCreated), m.createOrgWorkspace)
httpapi.Register(api, httpapi.Authorized(ActionUpdate, KindWorkspace), op("rename-org-workspace", http.MethodPatch, "/api/orgs/{id}/workspaces/{workspace}", "Rename a workspace", 0), m.renameOrgWorkspace)
httpapi.Register(api, httpapi.Authorized(ActionRead, KindOrg), op("list-org-events", http.MethodGet, "/api/orgs/{id}/history", "List the organisation's name changes", 0), m.listOrgEvents)
}
// caller returns the principal a request acts as. Every organisation route is
@@ -146,12 +146,12 @@ func (m *Module) ownerOf(ctx context.Context, kind ResourceKind, resourceID stri
// policyAllows evaluates the live chain for one write, so a forbid an operator
// wrote refuses it even when the caller's role would otherwise permit it.
func (m *Module) policyAllows(ctx context.Context, p Principal, action Action, kind ResourceKind, resourceID string, org OrgID, workspace WorkspaceID) error {
if m.authorizer == nil {
if m.authz() == nil {
return huma.Error503ServiceUnavailable("Access policies are unavailable.")
}
scoped := p
scoped.Org = org
decision := m.authorizer.Authorize(ctx, scoped, action, Resource{
decision := m.authz().Authorize(ctx, scoped, action, Resource{
Kind: kind, ID: resourceID, Org: org, Workspace: workspace,
}, AccessContext{Time: time.Now()})
switch {
+3 -2
View File
@@ -99,7 +99,8 @@ func (s Settings) path(eligible map[string]string, owner string) []PathStep {
// Holds reports whether the account is allowed every one of actions on r by
// the live access policies. It is false while no policy chain is attached.
func (m *Module) Holds(ctx context.Context, account IdentityID, r Resource, actions ...Action) (bool, error) {
if m.authorizer == nil {
authz := m.authz()
if authz == nil {
return false, nil
}
p, err := m.PrincipalFor(ctx, account)
@@ -107,7 +108,7 @@ func (m *Module) Holds(ctx context.Context, account IdentityID, r Resource, acti
return false, err
}
for _, a := range actions {
d := m.authorizer.Authorize(ctx, p, a, r, AccessContext{})
d := authz.Authorize(ctx, p, a, r, AccessContext{})
if d.Err != nil {
return false, d.Err
}
+54 -7
View File
@@ -1,19 +1,27 @@
package governance
import "slices"
const (
roleOwner = string(RoleOwner)
roleAdmin = string(RoleAdmin)
roleDeveloper = string(RoleDeveloper)
roleViewer = string(RoleViewer)
roleWorkload = string(RoleWorkload)
)
// Shipped policy IDs overwritten by seeding and org policy resets.
const (
PolicyOrgRead = "org-role-read"
PolicyOrgEdit = "org-role-edit"
PolicyOrgAdmin = "org-role-admin"
PolicyOrgOwner = "org-role-owner"
PolicyCrossOrgID = "instance-cross-org"
PolicyOrgRead = "org-role-read"
PolicyOrgEdit = "org-role-edit"
PolicyOrgAdmin = "org-role-admin"
PolicyOrgOwner = "org-role-owner"
// PolicyOrgWorkload grants the principal background work acts as.
PolicyOrgWorkload = "org-workload"
// PolicyOrgSelfService lets every member manage their own account,
// conversations and notes.
PolicyOrgSelfService = "org-self-service"
PolicyCrossOrgID = "instance-cross-org"
)
const orgReadPolicy = `permit(principal, action, resource) when {
@@ -40,8 +48,25 @@ const orgOwnerPolicy = `permit(principal, action, resource) when {
principal.role == "` + roleOwner + `"
};`
// ShippedOrgPolicies returns the four shipped role policies for one org.
func ShippedOrgPolicies(orgID OrgID) []Policy {
// orgWorkloadPolicy lets trigger dispatch, run workers and delivery workers do
// the work they were queued to do and nothing else.
const orgWorkloadPolicy = `permit(principal, action, resource) when {
resource.org == principal.org &&
principal.role == "` + roleWorkload + `" &&
action in [Archie::Action::"read", Archie::Action::"run", Archie::Action::"deliver"]
};`
// orgSelfServicePolicy lets any member use the account, conversation and note
// routes, whose handlers scope every row to the caller.
const orgSelfServicePolicy = `permit(principal, action, resource) when {
resource.org == principal.org &&
["` + roleViewer + `", "` + roleDeveloper + `", "` + roleAdmin + `", "` + roleOwner + `"].contains(principal.role) &&
["` + string(KindAccount) + `", "` + string(KindChatSession) + `", "` + string(KindNote) + `"].contains(resource.kind) &&
action in [Archie::Action::"read", Archie::Action::"create", Archie::Action::"update", Archie::Action::"delete"]
};`
// ShippedRolePolicies returns the four shipped role policies for one org.
func ShippedRolePolicies(orgID OrgID) []Policy {
return []Policy{
{ID: PolicyOrgRead, Level: LevelOrg, OrgID: orgID, Text: orgReadPolicy},
{ID: PolicyOrgEdit, Level: LevelOrg, OrgID: orgID, Text: orgEditPolicy},
@@ -50,6 +75,28 @@ func ShippedOrgPolicies(orgID OrgID) []Policy {
}
}
// ShippedWorkloadPolicy returns the shipped policy for the workload principal.
func ShippedWorkloadPolicy(orgID OrgID) Policy {
return Policy{ID: PolicyOrgWorkload, Level: LevelOrg, OrgID: orgID, Text: orgWorkloadPolicy}
}
// ShippedSelfServicePolicy returns the shipped policy for self-service routes.
func ShippedSelfServicePolicy(orgID OrgID) Policy {
return Policy{ID: PolicyOrgSelfService, Level: LevelOrg, OrgID: orgID, Text: orgSelfServicePolicy}
}
// shippedExtraPolicies are the shipped policies added after the role
// policies. Each is seeded on its own, so an org seeded before it existed
// still receives it.
func shippedExtraPolicies(orgID OrgID) []Policy {
return []Policy{ShippedWorkloadPolicy(orgID), ShippedSelfServicePolicy(orgID)}
}
// ShippedOrgPolicies returns every policy shipped for one org.
func ShippedOrgPolicies(orgID OrgID) []Policy {
return slices.Clip(append(ShippedRolePolicies(orgID), shippedExtraPolicies(orgID)...))
}
// CrossOrgForbidID is the ID reported in denial records for cross-org refusals.
const CrossOrgForbidID = PolicyCrossOrgID
+17 -4
View File
@@ -128,13 +128,26 @@ type policySeedStore interface {
// leaves none of it behind and the next attempt writes all of it. The store
// decides whether the seed already ran; an org that has any shipped policy is
// left alone, so a deletion or an edit an admin made stands across restarts.
//
// The later shipped policies are seeded one by one, so an org that was seeded
// before they existed still receives them.
func seedShippedPolicies(ctx context.Context, s policySeedStore, orgID OrgID) error {
shipped := ShippedOrgPolicies(orgID)
rows := make([]store.PolicyRow, 0, len(shipped))
for _, p := range shipped {
roles := ShippedRolePolicies(orgID)
rows := make([]store.PolicyRow, 0, len(roles))
ids := make([]string, 0, len(roles))
for _, p := range roles {
rows = append(rows, policyToRow(p))
ids = append(ids, p.ID)
}
return s.SeedOrgPolicies(ctx, string(orgID), shippedOrgPolicyIDs(), rows)
if err := s.SeedOrgPolicies(ctx, string(orgID), ids, rows); err != nil {
return err
}
for _, p := range shippedExtraPolicies(orgID) {
if err := s.SeedOrgPolicies(ctx, string(orgID), []string{p.ID}, []store.PolicyRow{policyToRow(p)}); err != nil {
return err
}
}
return nil
}
// ResetOrgPolicies removes non-shipped org policies and restores the shipped role policies.
+4 -3
View File
@@ -14,6 +14,7 @@ import (
"github.com/jmoiron/sqlx"
"github.com/samcharles93/archie-core/internal/platform/httpapi"
"github.com/samcharles93/archie-core/modules/governance"
"github.com/samcharles93/archie-core/modules/judgement/internal/store"
)
@@ -321,15 +322,15 @@ const bootstrapAdmin = "admin"
// Register adds the action classes API.
func (c *Classes) Register(api huma.API, outcomes Outcomes) {
tags := []string{"Controls"}
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindClass), huma.Operation{
OperationID: "list-classes", Method: http.MethodGet, Path: "/api/classes",
Summary: "List action classes with their earned levels", Tags: tags,
}, c.list)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindClass), huma.Operation{
OperationID: "get-class", Method: http.MethodGet, Path: "/api/classes/{id}",
Summary: "Get an action class with its history and outcomes", Tags: tags,
}, c.detail(outcomes))
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindClass), huma.Operation{
OperationID: "reset-class", Method: http.MethodPost, Path: "/api/classes/{id}/reset",
Summary: "Reset an action class to its default level", Tags: tags,
}, c.reset)
+2 -1
View File
@@ -10,6 +10,7 @@ import (
"github.com/samcharles93/archie-core/internal/platform/httpapi"
"github.com/samcharles93/archie-core/modules/connectors"
"github.com/samcharles93/archie-core/modules/governance"
)
// judgeScanLimit bounds the decisions the control page reads to find a
@@ -90,7 +91,7 @@ func (m *Module) latestJudge(ctx context.Context, guard string) (*JudgeStanding,
// Register adds the judgement controls API.
func (m *Module) Register(api huma.API) {
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindGuard), huma.Operation{
OperationID: "list-judges", Method: http.MethodGet, Path: "/api/controls/judges",
Summary: "List each guard's judge, its standing and its eval date", Tags: []string{"Controls"},
}, m.listJudges)
+3 -2
View File
@@ -23,6 +23,7 @@ import (
"github.com/samcharles93/archie-core/internal/platform/httpapi"
"github.com/samcharles93/archie-core/modules/connectors"
"github.com/samcharles93/archie-core/modules/governance"
"github.com/samcharles93/archie-core/modules/judgement/internal/store"
)
@@ -389,11 +390,11 @@ func (p *Policies) Register(api huma.API) {
{KindHardRules, "/api/policies/hard-rules", "hard-rules", "hard rules"},
{KindChangeRequest, "/api/policies/change-request", "change-request-rules", "change-request rules"},
} {
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindGuard), huma.Operation{
OperationID: "get-" + k.id, Method: http.MethodGet, Path: k.path,
Summary: "Get the " + k.noun, Tags: tags,
}, p.get(k.kind))
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindGuard), huma.Operation{
OperationID: "put-" + k.id, Method: http.MethodPut, Path: k.path,
Summary: "Replace the " + k.noun + " with a new version", Tags: tags,
}, p.put(k.kind))
+21 -22
View File
@@ -15,59 +15,58 @@ import (
// Register adds the memory API. The routes a person uses to read and correct
// their own notes are scoped to the signed-in caller; the ones that publish,
// revoke or roll back a shared note need an instance administrator, which
// httpapi enforces unless an operation opts into SignedIn.
// revoke or roll back a shared note need an instance administrator.
func (m *Module) Register(api huma.API) {
tags := []string{"Memory"}
huma.Register(api, httpapi.SignedIn(huma.Operation{
httpapi.Register(api, httpapi.Authorized(governance.ActionRead, governance.KindNote), huma.Operation{
OperationID: "list-memory-notes", Method: http.MethodGet, Path: "/api/memory/notes",
Summary: "List the notes you may read", Tags: tags,
}), m.notesOfCaller)
huma.Register(api, httpapi.SignedIn(huma.Operation{
}, m.notesOfCaller)
httpapi.Register(api, httpapi.Authorized(governance.ActionCreate, governance.KindNote), huma.Operation{
OperationID: "remember-memory-note", Method: http.MethodPost, Path: "/api/memory/notes",
Summary: "Remember a note for yourself", Tags: tags,
}), m.rememberNote)
huma.Register(api, httpapi.SignedIn(huma.Operation{
}, m.rememberNote)
httpapi.Register(api, httpapi.Authorized(governance.ActionUpdate, governance.KindNote), huma.Operation{
OperationID: "correct-memory-note", Method: http.MethodPatch, Path: "/api/memory/notes/{id}",
Summary: "Correct one of your notes", Tags: tags,
}), m.correctNote)
huma.Register(api, httpapi.SignedIn(huma.Operation{
}, m.correctNote)
httpapi.Register(api, httpapi.Authorized(governance.ActionUpdate, governance.KindNote), huma.Operation{
OperationID: "disable-memory-note", Method: http.MethodPost, Path: "/api/memory/notes/{id}/disabled",
Summary: "Stop one of your notes being read, or resume it", Tags: tags,
}), m.disableNote)
huma.Register(api, httpapi.SignedIn(huma.Operation{
}, m.disableNote)
httpapi.Register(api, httpapi.Authorized(governance.ActionDelete, governance.KindNote), huma.Operation{
OperationID: "forget-memory-note", Method: http.MethodDelete, Path: "/api/memory/notes/{id}",
Summary: "Forget one of your notes", Tags: tags,
}), m.forgetNote)
huma.Register(api, httpapi.SignedIn(huma.Operation{
}, m.forgetNote)
httpapi.Register(api, httpapi.Authorized(governance.ActionCreate, governance.KindNote), huma.Operation{
OperationID: "propose-shared-note", Method: http.MethodPost, Path: "/api/memory/proposals",
Summary: "Propose a note for the whole organisation", Tags: tags,
}), m.proposeNote)
huma.Register(api, httpapi.SignedIn(huma.Operation{
}, m.proposeNote)
httpapi.Register(api, httpapi.Authorized(governance.ActionRead, governance.KindMemory), huma.Operation{
OperationID: "list-shared-notes", Method: http.MethodGet, Path: "/api/memory/shared",
Summary: "List the notes published to the organisation", Tags: tags,
}), m.sharedNotes)
huma.Register(api, huma.Operation{
}, m.sharedNotes)
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionCreate, governance.KindMemory), huma.Operation{
OperationID: "publish-shared-note", Method: http.MethodPost, Path: "/api/memory/shared",
Summary: "Publish a note to the whole organisation", Tags: tags,
}, m.publishNote)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindMemory), huma.Operation{
OperationID: "list-note-proposals", Method: http.MethodGet, Path: "/api/memory/proposals",
Summary: "List notes waiting to be published", Tags: tags,
}, m.pendingNotes)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindMemory), huma.Operation{
OperationID: "approve-note-proposal", Method: http.MethodPost, Path: "/api/memory/proposals/{id}/publish",
Summary: "Publish a proposed note", Tags: tags,
}, m.approveNote)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionDelete, governance.KindMemory), huma.Operation{
OperationID: "revoke-shared-note", Method: http.MethodDelete, Path: "/api/memory/shared/{id}",
Summary: "Revoke a shared note, published or proposed", Tags: tags,
}, m.revokeNote)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindMemory), huma.Operation{
OperationID: "list-note-versions", Method: http.MethodGet, Path: "/api/memory/shared/{id}/versions",
Summary: "List the published versions of a shared note", Tags: tags,
}, m.noteVersions)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindMemory), huma.Operation{
OperationID: "roll-back-shared-note", Method: http.MethodPost, Path: "/api/memory/shared/{id}/rollback",
Summary: "Publish an earlier version of a shared note again", Tags: tags,
}, m.rollbackNote)
+133
View File
@@ -0,0 +1,133 @@
package runs
import (
"context"
"encoding/json/jsontext"
"errors"
"log/slog"
"slices"
"strings"
"testing"
"time"
"github.com/google/uuid"
"github.com/samcharles93/archie-core/modules/governance"
"github.com/samcharles93/archie-core/modules/runs/internal/store"
)
// asked is one decision the engine requested.
type asked struct {
principal governance.IdentityID
action governance.Action
kind governance.ResourceKind
id string
}
// recordingAccess answers every Authorize with one fixed decision and records
// what was asked.
type recordingAccess struct {
decision governance.Decision
calls []asked
}
func (r *recordingAccess) Authorize(_ context.Context, p governance.Principal, a governance.Action, res governance.Resource, _ governance.AccessContext) governance.Decision {
r.calls = append(r.calls, asked{p.IdentityID, a, res.Kind, res.ID})
return r.decision
}
// queueingStore holds the runs the engine queues.
type queueingStore struct {
fakeWork
queued []store.NewRun
}
func (q *queueingStore) Start(_ context.Context, n store.NewRun) (uuid.UUID, error) {
q.queued = append(q.queued, n)
return uuid.New(), nil
}
// claimsOne hands out one queued run to the worker, as the store does after a
// restart or a retry.
type claimsOne struct {
*queueingStore
run store.Run
}
func (c claimsOne) Claim(context.Context, string, uuid.UUID, time.Duration) (store.Run, bool, error) {
return c.run, true, nil
}
// TestRunsAreAuthorizedAtStartAndAtEveryClaim guards that a run started by a
// trigger and the same run claimed again after a restart or a retry are decided
// by the same live check, as the workload principal, and that a refusal stops
// the work. A policy chain that can't decide starts nothing, finishes nothing
// and leaves the run for another attempt. Without it a revoked grant would
// keep running queued work.
func TestRunsAreAuthorizedAtStartAndAtEveryClaim(t *testing.T) {
workload := asked{governance.WorkloadID, governance.ActionRun, governance.KindWorkflow, "triage"}
tests := []struct {
name string
decision governance.Decision
noPrincipal bool
claim bool
wantCalls []asked
wantQueued int
wantRan bool
wantFinished []string
wantErr error
}{
{name: "a trigger starts its run", decision: governance.Allowed(), wantCalls: []asked{workload}, wantQueued: 1},
{name: "a start with no principal", decision: governance.Allowed(), noPrincipal: true, wantErr: governance.ErrDenied},
{name: "a revoked start", decision: governance.DeniedAt(governance.LevelOrg, []string{"org-workload"}), wantCalls: []asked{workload}, wantErr: governance.ErrDenied},
{name: "a start the chain can't decide", decision: governance.Unavailable(), wantCalls: []asked{workload}, wantErr: governance.ErrChainUnavailable},
{name: "a claim after a restart", decision: governance.Allowed(), claim: true, wantCalls: []asked{workload}, wantRan: true, wantFinished: []string{store.StateSucceeded}},
{name: "a claim after revocation", decision: governance.DeniedAt(governance.LevelOrg, []string{"org-workload"}), claim: true, wantCalls: []asked{workload}, wantFinished: []string{store.StateFailed}},
{name: "a claim the chain can't decide", decision: governance.Unavailable(), claim: true, wantCalls: []asked{workload}, wantErr: governance.ErrChainUnavailable},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
work := &queueingStore{}
access := &recordingAccess{decision: tt.decision}
engine := newEngine(nil, work, slog.New(slog.DiscardHandler), Options{})
engine.queue = work
engine.Use(Deps{Access: access})
ran := false
useWorkflow(engine, func(*Context, jsontext.Value) (jsontext.Value, error) {
ran = true
return jsontext.Value(`"done"`), nil
})
var err error
if tt.claim {
engine.work = claimsOne{work, store.Run{ID: uuid.New(), OrgID: "org", Workflow: "triage", Version: 1, Input: jsontext.Value(`null`)}}
_, err = engine.claimAndExecute(t.Context())
} else {
ctx := t.Context()
if !tt.noPrincipal {
ctx = governance.WithPrincipal(ctx, governance.WorkloadPrincipal(governance.DefaultOrgID))
}
_, err = engine.Start(ctx, StartRequest{OrgID: "org", Workflow: "triage", Key: "event:trigger"})
}
if !errors.Is(err, tt.wantErr) {
t.Fatalf("error = %v, want %v", err, tt.wantErr)
}
if !slices.Equal(access.calls, tt.wantCalls) {
t.Fatalf("decisions asked = %v, want %v", access.calls, tt.wantCalls)
}
if len(work.queued) != tt.wantQueued {
t.Fatalf("runs queued = %d, want %d", len(work.queued), tt.wantQueued)
}
if ran != tt.wantRan {
t.Fatalf("workflow ran = %v, want %v", ran, tt.wantRan)
}
if !slices.Equal(work.finished, tt.wantFinished) {
t.Fatalf("finished = %v, want %v", work.finished, tt.wantFinished)
}
if slices.Contains(tt.wantFinished, store.StateFailed) && !strings.Contains(work.errors[0], "not permitted") {
t.Fatalf("the run's trail says %q, want the refusal", work.errors[0])
}
})
}
}
+4 -1
View File
@@ -73,6 +73,9 @@ type DryRequest struct {
// StartDry queues a dry run of a document and returns its run's id. A document
// that doesn't validate starts nothing.
func (e *Engine) StartDry(ctx context.Context, req DryRequest) (uuid.UUID, error) {
if err := e.mayStart(ctx, req.Workflow); err != nil {
return uuid.Nil, err
}
doc, err := e.validateDocument(ctx, req.Document)
if err != nil {
return uuid.Nil, err
@@ -93,7 +96,7 @@ func (e *Engine) StartDry(ctx context.Context, req DryRequest) (uuid.UUID, error
if err := doc.checkInputs(decodeInputs(input)); err != nil {
return uuid.Nil, fmt.Errorf("workflow %q: %w", req.Workflow, err)
}
return e.db.Start(ctx, store.NewRun{
return e.queue.Start(ctx, store.NewRun{
OrgID: req.OrgID, Workflow: req.Workflow, Input: input, Dry: true, Overlay: overlay,
})
}
+4 -1
View File
@@ -10,6 +10,7 @@ import (
"github.com/google/uuid"
"github.com/samcharles93/archie-core/modules/connectors"
"github.com/samcharles93/archie-core/modules/governance"
"github.com/samcharles93/archie-core/modules/judgement"
"github.com/samcharles93/archie-core/modules/runs/internal/store"
)
@@ -48,6 +49,7 @@ func (anyBox) Tool(string) (connectors.Tool, bool) { return nil, true }
// is queued.
func TestStartDryRefusesWhatCannotStart(t *testing.T) {
engine := newEngine(nil, &fakeWork{}, slog.New(slog.DiscardHandler), Options{})
engine.Use(Deps{Access: &recordingAccess{decision: governance.Allowed()}})
tests := []struct {
name string
doc string
@@ -71,7 +73,8 @@ func TestStartDryRefusesWhatCannotStart(t *testing.T) {
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
_, err := engine.StartDry(context.Background(), DryRequest{
ctx := governance.WithPrincipal(context.Background(), governance.SharedTokenOwner())
_, err := engine.StartDry(ctx, DryRequest{
OrgID: "org", Workflow: "draft", Document: tt.doc,
})
if err == nil || !strings.Contains(err.Error(), tt.want) {
+4
View File
@@ -103,6 +103,10 @@ type Deps struct {
// Capabilities is what saving a workflow checks connector references
// against.
Capabilities Capabilities
// Access decides whether a run may start and whether a claimed run may
// execute, for the principal acting or else the workload principal. With
// none, no run starts or executes.
Access governance.Authorizer
}
// Workflow is a document ready to run: the code that executes its steps for
+71 -10
View File
@@ -64,12 +64,14 @@ type runStarter interface {
// Engine starts, executes and resumes runs.
type Engine struct {
db *store.Store
work runWork
log *slog.Logger
opts Options
mu sync.RWMutex
deps *Deps
db *store.Store
// queue starts runs; it is db except in tests.
queue runQueue
work runWork
log *slog.Logger
opts Options
mu sync.RWMutex
deps *Deps
// load turns a claimed run into the code that executes it.
load func(ctx context.Context, run store.Run) (Workflow, error)
}
@@ -93,7 +95,7 @@ func newEngine(db *store.Store, work runWork, log *slog.Logger, opts Options) *E
if opts.Owner == "" {
opts.Owner = "archie"
}
e := &Engine{db: db, work: work, log: log, opts: opts}
e := &Engine{db: db, queue: db, work: work, log: log, opts: opts}
e.load = e.loadDocument
return e
}
@@ -185,14 +187,42 @@ func (e *Engine) Has(ctx context.Context, orgID, name string) (bool, error) {
return err == nil, err
}
// runQueue reads the workflow a run starts under and queues the run.
type runQueue interface {
workflowFinder
Start(ctx context.Context, n store.NewRun) (uuid.UUID, error)
}
// Start queues a run under the latest stored version of its workflow and
// returns its id.
// returns its id. The principal in ctx must be allowed to run the workflow;
// work that starts runs on its own, such as a trigger, passes the workload
// principal. A start the policy chain can't decide queues nothing, and the
// error wraps governance.ErrChainUnavailable so the caller tries again.
func (e *Engine) Start(ctx context.Context, req StartRequest) (uuid.UUID, error) {
n, err := newRun(ctx, e.db, req)
if err := e.mayStart(ctx, req.Workflow); err != nil {
return uuid.Nil, err
}
n, err := newRun(ctx, e.queue, req)
if err != nil {
return uuid.Nil, err
}
return e.db.Start(ctx, n)
return e.queue.Start(ctx, n)
}
// mayStart refuses a start by a caller who may not run workflow, or whose
// right can't be checked.
func (e *Engine) mayStart(ctx context.Context, workflow string) error {
p, ok := governance.PrincipalFromContext(ctx)
if !ok {
return fmt.Errorf("%w: no principal starts the run", governance.ErrDenied)
}
deps, err := e.steps()
if err != nil {
return fmt.Errorf("%w: %w", governance.ErrChainUnavailable, err)
}
return governance.Require(ctx, deps.Access, p, governance.ActionRun, governance.Resource{
Kind: governance.KindWorkflow, ID: workflow, Org: p.Org,
})
}
// workflowFinder reads stored workflow versions.
@@ -320,10 +350,41 @@ func (e *Engine) claimAndExecute(ctx context.Context) (bool, error) {
if err != nil || !ok {
return false, err
}
if err := e.mayExecute(ctx, run); err != nil {
return e.refuseClaim(ctx, run, token, err)
}
e.execute(ctx, run, token)
return true, nil
}
// mayExecute rechecks, each time a worker claims a run, that the workload
// principal may still run its workflow. A new run, a retry and a resume after
// a crash or a wake-up all pass through here.
func (e *Engine) mayExecute(ctx context.Context, run store.Run) error {
deps, err := e.steps()
if err != nil {
return fmt.Errorf("%w: %w", governance.ErrChainUnavailable, err)
}
return governance.RequireWorkload(ctx, deps.Access, governance.ActionRun, governance.Resource{
Kind: governance.KindWorkflow, ID: run.Workflow,
})
}
// refuseClaim handles a claimed run that may not execute. A policy chain that
// can't decide leaves the run unfinished, so its lease lapses and a worker
// claims it again. A refusal ends the run as failed, and its trail says why.
func (e *Engine) refuseClaim(ctx context.Context, run store.Run, token uuid.UUID, cause error) (bool, error) {
if !errors.Is(cause, governance.ErrDenied) {
return false, fmt.Errorf("run %s waits for access policies: %w", run.ID, cause)
}
ended := store.Ended{State: store.StateFailed, Error: cause.Error()}
if err := e.work.Finish(ctx, run.ID, token, ended); err != nil {
return false, fmt.Errorf("finish refused run %s: %w", run.ID, err)
}
e.log.WarnContext(ctx, "run refused", "run", run.ID, "workflow", run.Workflow, "error", cause)
return true, nil
}
// execute runs one claimed run to its next suspension or end. The run's
// context ends if the lease can't be renewed, so a stale worker stops.
func (e *Engine) execute(ctx context.Context, run store.Run, token uuid.UUID) {
+5 -4
View File
@@ -17,6 +17,7 @@ import (
"github.com/samcharles93/archie-core/internal/platform/httpapi"
"github.com/samcharles93/archie-core/modules/approvals"
"github.com/samcharles93/archie-core/modules/governance"
"github.com/samcharles93/archie-core/modules/judgement"
"github.com/samcharles93/archie-core/modules/runs/internal/store"
)
@@ -139,19 +140,19 @@ type Approvals interface {
func (e *Engine) Register(api huma.API, orgID string, origins Origins, decisions Decisions, asked Approvals) {
a := &runAPI{engine: e, db: e.db, orgID: orgID, origins: origins, decisions: decisions, approvals: asked}
tags := []string{"Runs"}
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindRun), huma.Operation{
OperationID: "list-runs", Method: http.MethodGet, Path: "/api/runs",
Summary: "List recent runs", Tags: tags,
}, a.recent)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindRun), huma.Operation{
OperationID: "get-run", Method: http.MethodGet, Path: "/api/runs/{id}",
Summary: "Get a run's decision trail", Tags: tags,
}, a.trail)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRun, governance.KindRun), huma.Operation{
OperationID: "retry-run", Method: http.MethodPost, Path: "/api/runs/{id}/retry",
Summary: "Retry a parked run from a step, keeping the results of the steps before it", Tags: tags,
}, a.retry)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindRun), huma.Operation{
OperationID: "cancel-run", Method: http.MethodPost, Path: "/api/runs/{id}/cancel",
Summary: "Cancel a run and the runs it started with workflow.call", Tags: tags,
}, a.cancel)
+5 -4
View File
@@ -10,6 +10,7 @@ import (
"github.com/samcharles93/archie-core/internal/platform/httpapi"
"github.com/samcharles93/archie-core/internal/platform/stableid"
"github.com/samcharles93/archie-core/modules/governance"
"github.com/samcharles93/archie-core/modules/runs/internal/store"
)
@@ -43,19 +44,19 @@ type workflowAPI struct {
func (e *Engine) registerWorkflows(api huma.API, orgID string) {
a := &workflowAPI{e: e, orgID: orgID}
tags := []string{"Workflows"}
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindWorkflow), huma.Operation{
OperationID: "list-workflows", Method: http.MethodGet, Path: "/api/workflows",
Summary: "List every workflow at its latest version", Tags: tags,
}, a.list)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindWorkflow), huma.Operation{
OperationID: "get-workflow", Method: http.MethodGet, Path: "/api/workflows/{name}",
Summary: "Get a workflow", Tags: tags,
}, a.get)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindWorkflow), huma.Operation{
OperationID: "put-workflow", Method: http.MethodPut, Path: "/api/workflows/{name}",
Summary: "Save a workflow document as its next version", Tags: tags,
}, a.put)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindWorkflow), huma.Operation{
OperationID: "list-workflow-step-types", Method: http.MethodGet, Path: "/api/workflow-step-types",
Summary: "List the step types a workflow document may name, with their settings schemas", Tags: tags,
}, a.stepTypes)
+3 -2
View File
@@ -16,6 +16,7 @@ import (
"github.com/samcharles93/archie-core/internal/platform/httpapi"
"github.com/samcharles93/archie-core/internal/platform/httpjson"
"github.com/samcharles93/archie-core/modules/governance"
)
// Bootstrap is what the binary loaded from config.toml, reduced to values safe
@@ -46,11 +47,11 @@ func New(b Bootstrap, rotate func(hash string) error, log *slog.Logger) *Module
// Register adds the system API.
func (m *Module) Register(api huma.API) {
tags := []string{"System"}
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindInstance), huma.Operation{
OperationID: "get-bootstrap", Method: http.MethodGet, Path: "/api/system/bootstrap",
Summary: "Get the bootstrap values, which only the config file sets", Tags: tags,
}, m.getBootstrap)
huma.Register(api, huma.Operation{
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindInstance), huma.Operation{
OperationID: "rotate-admin-token", Method: http.MethodPost, Path: "/api/admin/token",
Summary: "Rotate the admin token; the new one is shown once", Tags: tags,
}, m.rotateAdminToken)