From 6c59d6b742ab4723da749029624061982306c6e5 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sun, 22 Nov 2026 02:15:02 +1100 Subject: [PATCH 1/2] feat(httpapi): refuse every API operation that does not declare its access (#2078) Operations register through httpapi.Register with Public, Authorized or AdminAuthorized, and the guard asks the policy chain for the declared action and resource kind before the handler runs. An undeclared operation and an undecidable chain are refused. The workload principal, its shipped policy, a self-service policy and Recording for denials are added in governance. --- internal/app/archie/access_test.go | 113 ++++++++++++++++ internal/app/archie/api.go | 12 +- internal/app/archie/run.go | 2 +- internal/platform/httpapi/httpapi.go | 150 ++++++++++++++++++---- internal/platform/httpapi/httpapi_test.go | 132 ++++++++++++++----- modules/approvals/dashboard.go | 10 +- modules/chat/access_test.go | 7 +- modules/chat/api.go | 36 +++--- modules/connectors/module.go | 19 +-- modules/dashboard/stream.go | 4 +- modules/dashboard/stream_test.go | 7 +- modules/drafts/drafts.go | 13 +- modules/events/api.go | 17 +-- modules/governance/access.go | 3 + modules/governance/access_test.go | 25 +++- modules/governance/accounts_api.go | 52 ++++---- modules/governance/enforce.go | 99 ++++++++++++++ modules/governance/enforce_test.go | 111 ++++++++++++++++ modules/governance/governance.go | 29 +++-- modules/governance/org.go | 3 + modules/governance/orgs_api.go | 24 ++-- modules/governance/roles.go | 61 ++++++++- modules/governance/store_access.go | 21 ++- modules/judgement/classes.go | 7 +- modules/judgement/judges.go | 3 +- modules/judgement/policies.go | 5 +- modules/memory/api.go | 43 +++---- modules/runs/trail.go | 9 +- modules/runs/workflows_api.go | 9 +- modules/system/system.go | 5 +- 30 files changed, 814 insertions(+), 217 deletions(-) create mode 100644 internal/app/archie/access_test.go create mode 100644 modules/governance/enforce.go create mode 100644 modules/governance/enforce_test.go diff --git a/internal/app/archie/access_test.go b/internal/app/archie/access_test.go new file mode 100644 index 000000000..0f11aef97 --- /dev/null +++ b/internal/app/archie/access_test.go @@ -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) + } +} diff --git a/internal/app/archie/api.go b/internal/app/archie/api.go index 6493c9103..0058ec5c6 100644 --- a/internal/app/archie/api.go +++ b/internal/app/archie/api.go @@ -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 } diff --git a/internal/app/archie/run.go b/internal/app/archie/run.go index 6c41b40f6..8d81cd142 100644 --- a/internal/app/archie/run.go +++ b/internal/app/archie/run.go @@ -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, diff --git a/internal/platform/httpapi/httpapi.go b/internal/platform/httpapi/httpapi.go index e10f84016..c8380fbe4 100644 --- a/internal/platform/httpapi/httpapi.go +++ b/internal/platform/httpapi/httpapi.go @@ -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 { diff --git a/internal/platform/httpapi/httpapi_test.go b/internal/platform/httpapi/httpapi_test.go index 64abee8ab..974ffa9b1 100644 --- a/internal/platform/httpapi/httpapi_test.go +++ b/internal/platform/httpapi/httpapi_test.go @@ -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") + } +} diff --git a/modules/approvals/dashboard.go b/modules/approvals/dashboard.go index 65c2d319b..57946ded5 100644 --- a/modules/approvals/dashboard.go +++ b/modules/approvals/dashboard.go @@ -109,18 +109,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 { diff --git a/modules/chat/access_test.go b/modules/chat/access_test.go index 154739856..3691cfbc7 100644 --- a/modules/chat/access_test.go +++ b/modules/chat/access_test.go @@ -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 } diff --git a/modules/chat/api.go b/modules/chat/api.go index 9a73b1043..d8207fa3e 100644 --- a/modules/chat/api.go +++ b/modules/chat/api.go @@ -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. diff --git a/modules/connectors/module.go b/modules/connectors/module.go index 8f5ccc57f..5eb007515 100644 --- a/modules/connectors/module.go +++ b/modules/connectors/module.go @@ -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. @@ -307,46 +308,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) diff --git a/modules/dashboard/stream.go b/modules/dashboard/stream.go index 27f24ebb9..ea4da8d59 100644 --- a/modules/dashboard/stream.go +++ b/modules/dashboard/stream.go @@ -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() {} diff --git a/modules/dashboard/stream_test.go b/modules/dashboard/stream_test.go index 3dddb5718..a419313f4 100644 --- a/modules/dashboard/stream_test.go +++ b/modules/dashboard/stream_test.go @@ -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 } diff --git a/modules/drafts/drafts.go b/modules/drafts/drafts.go index 5462ef777..e2cc99632 100644 --- a/modules/drafts/drafts.go +++ b/modules/drafts/drafts.go @@ -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) diff --git a/modules/events/api.go b/modules/events/api.go index 5ae200e97..9da5a6241 100644 --- a/modules/events/api.go +++ b/modules/events/api.go @@ -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) diff --git a/modules/governance/access.go b/modules/governance/access.go index 27be1b203..2ba6447df 100644 --- a/modules/governance/access.go +++ b/modules/governance/access.go @@ -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. diff --git a/modules/governance/access_test.go b/modules/governance/access_test.go index cef110256..fbc9fd2ab 100644 --- a/modules/governance/access_test.go +++ b/modules/governance/access_test.go @@ -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)) diff --git a/modules/governance/accounts_api.go b/modules/governance/accounts_api.go index 1fffed28e..b7e5f14f5 100644 --- a/modules/governance/accounts_api.go +++ b/modules/governance/accounts_api.go @@ -88,39 +88,33 @@ 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) - 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) + 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. diff --git a/modules/governance/enforce.go b/modules/governance/enforce.go new file mode 100644 index 000000000..7331fe452 --- /dev/null +++ b/modules/governance/enforce.go @@ -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 +} diff --git a/modules/governance/enforce_test.go b/modules/governance/enforce_test.go new file mode 100644 index 000000000..32dbec818 --- /dev/null +++ b/modules/governance/enforce_test.go @@ -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) + } + }) + } +} diff --git a/modules/governance/governance.go b/modules/governance/governance.go index 45d900a59..14c2c292e 100644 --- a/modules/governance/governance.go +++ b/modules/governance/governance.go @@ -16,6 +16,7 @@ import ( "regexp" "slices" "strings" + "sync/atomic" "time" "github.com/danielgtaylor/huma/v2" @@ -256,7 +257,7 @@ type Module struct { store *store.Store log *slog.Logger credentials Credentials - authorizer Authorizer + authorizer atomic.Pointer[Authorizer] oidc *oidcLogin setup *SetupSignal } @@ -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) { @@ -389,35 +398,35 @@ func (m *Module) ApprovalDeadline(ctx context.Context) (time.Duration, error) { // people. 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: "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) - huma.Register(api, huma.Operation{ + httpapi.Register(api, httpapi.AdminAuthorized(ActionRead, KindMember), huma.Operation{ OperationID: "list-people", Method: http.MethodGet, Path: "/api/people", Summary: "List the people", Tags: tags, }, m.getPeople) - huma.Register(api, huma.Operation{ + httpapi.Register(api, httpapi.AdminAuthorized(ActionUpdate, KindMember), huma.Operation{ OperationID: "put-people", Method: http.MethodPut, Path: "/api/people", Summary: "Replace the people", Tags: tags, }, m.putPeople) diff --git a/modules/governance/org.go b/modules/governance/org.go index 214eb6957..599b0c199 100644 --- a/modules/governance/org.go +++ b/modules/governance/org.go @@ -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. diff --git a/modules/governance/orgs_api.go b/modules/governance/orgs_api.go index fbab14b3e..f54d05217 100644 --- a/modules/governance/orgs_api.go +++ b/modules/governance/orgs_api.go @@ -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 { diff --git a/modules/governance/roles.go b/modules/governance/roles.go index a26693566..c1f732999 100644 --- a/modules/governance/roles.go +++ b/modules/governance/roles.go @@ -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 diff --git a/modules/governance/store_access.go b/modules/governance/store_access.go index bf433d681..98a4134eb 100644 --- a/modules/governance/store_access.go +++ b/modules/governance/store_access.go @@ -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. diff --git a/modules/judgement/classes.go b/modules/judgement/classes.go index 54ac6afa3..96a629ce1 100644 --- a/modules/judgement/classes.go +++ b/modules/judgement/classes.go @@ -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) diff --git a/modules/judgement/judges.go b/modules/judgement/judges.go index 161f7460a..896d3b363 100644 --- a/modules/judgement/judges.go +++ b/modules/judgement/judges.go @@ -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) diff --git a/modules/judgement/policies.go b/modules/judgement/policies.go index 41e20b73d..6bc6be5b1 100644 --- a/modules/judgement/policies.go +++ b/modules/judgement/policies.go @@ -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)) diff --git a/modules/memory/api.go b/modules/memory/api.go index c4ec8f4d5..d8170317f 100644 --- a/modules/memory/api.go +++ b/modules/memory/api.go @@ -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) diff --git a/modules/runs/trail.go b/modules/runs/trail.go index 76f2dcbc7..26e4286ef 100644 --- a/modules/runs/trail.go +++ b/modules/runs/trail.go @@ -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) diff --git a/modules/runs/workflows_api.go b/modules/runs/workflows_api.go index a5020592a..26d143043 100644 --- a/modules/runs/workflows_api.go +++ b/modules/runs/workflows_api.go @@ -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) diff --git a/modules/system/system.go b/modules/system/system.go index 7e81176ac..cd3ef3cb8 100644 --- a/modules/system/system.go +++ b/modules/system/system.go @@ -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) From 098d8cc3286839cf874fdfd906c699bdd320982d Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sun, 22 Nov 2026 02:15:05 +1100 Subject: [PATCH 2/2] feat(runs): authorize runs, deliveries and intake as the workload principal (#2078) Trigger dispatch, run start, every run claim, every delivery attempt and webhook intake now ask the policy chain. Background work acts as the workload principal; a refusal is final and recorded on the run or the delivery, and an undecidable chain leaves the work queued for another attempt. Intake applies the per-source delivery policy after source verification. --- internal/app/archie/operations.go | 13 ++- modules/deliveries/access_test.go | 107 ++++++++++++++++++++ modules/deliveries/deliveries.go | 46 +++++++-- modules/events/access_test.go | 163 ++++++++++++++++++++++++++++++ modules/events/events.go | 112 ++++++++++++++++---- modules/events/schedule.go | 2 +- modules/events/verify_test.go | 10 +- modules/runs/access_test.go | 133 ++++++++++++++++++++++++ modules/runs/dry.go | 5 +- modules/runs/dry_test.go | 5 +- modules/runs/interpreter.go | 4 + modules/runs/runs.go | 81 +++++++++++++-- 12 files changed, 639 insertions(+), 42 deletions(-) create mode 100644 modules/deliveries/access_test.go create mode 100644 modules/events/access_test.go create mode 100644 modules/runs/access_test.go diff --git a/internal/app/archie/operations.go b/internal/app/archie/operations.go index 6bb080635..cfd2d1f66 100644 --- a/internal/app/archie/operations.go +++ b/internal/app/archie/operations.go @@ -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,9 +80,12 @@ 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) + // 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.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, diff --git a/modules/deliveries/access_test.go b/modules/deliveries/access_test.go new file mode 100644 index 000000000..4b7f7ef43 --- /dev/null +++ b/modules/deliveries/access_test.go @@ -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) + } + } + }) + } +} diff --git a/modules/deliveries/deliveries.go b/modules/deliveries/deliveries.go index 79f6edfc4..aeca627e3 100644 --- a/modules/deliveries/deliveries.go +++ b/modules/deliveries/deliveries.go @@ -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": { diff --git a/modules/events/access_test.go b/modules/events/access_test.go new file mode 100644 index 000000000..64a15466d --- /dev/null +++ b/modules/events/access_test.go @@ -0,0 +1,163 @@ +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 +} + +// 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) + } + }) + } +} diff --git a/modules/events/events.go b/modules/events/events.go index 834cfb11f..8a07a448a 100644 --- a/modules/events/events.go +++ b/modules/events/events.go @@ -16,6 +16,7 @@ import ( "errors" "fmt" "log/slog" + "net" "net/http" "regexp" "sync" @@ -28,6 +29,7 @@ import ( "github.com/samcharles93/archie-core/modules/connectors" "github.com/samcharles93/archie-core/modules/events/internal/match" "github.com/samcharles93/archie-core/modules/events/internal/store" + "github.com/samcharles93/archie-core/modules/governance" "github.com/samcharles93/archie-core/modules/runs" ) @@ -71,6 +73,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 @@ -84,7 +88,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, d Deliveries) *Module { st := store.New(db) - m := &Module{orgID: orgID, store: st, reader: st, sealer: sealer, connectors: c, runs: r, answers: a, 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, deliveries: d, log: log, poll: time.Second} m.parse = m.parseWith return m } @@ -94,15 +98,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 { @@ -151,6 +166,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 @@ -176,6 +194,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) @@ -193,7 +241,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 } @@ -332,7 +380,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 { @@ -341,11 +389,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 @@ -353,18 +403,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) diff --git a/modules/events/schedule.go b/modules/events/schedule.go index ec13ebd56..1df8c2cc9 100644 --- a/modules/events/schedule.go +++ b/modules/events/schedule.go @@ -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 } diff --git a/modules/events/verify_test.go b/modules/events/verify_test.go index 5d8a024ac..5568a95f6 100644 --- a/modules/events/verify_test.go +++ b/modules/events/verify_test.go @@ -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() +} diff --git a/modules/runs/access_test.go b/modules/runs/access_test.go new file mode 100644 index 000000000..bb8259b7c --- /dev/null +++ b/modules/runs/access_test.go @@ -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]) + } + }) + } +} diff --git a/modules/runs/dry.go b/modules/runs/dry.go index 7b3ae3559..89c64fe46 100644 --- a/modules/runs/dry.go +++ b/modules/runs/dry.go @@ -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, }) } diff --git a/modules/runs/dry_test.go b/modules/runs/dry_test.go index ca3132312..fd4723bd5 100644 --- a/modules/runs/dry_test.go +++ b/modules/runs/dry_test.go @@ -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) { diff --git a/modules/runs/interpreter.go b/modules/runs/interpreter.go index cbe59adb1..91fe269f6 100644 --- a/modules/runs/interpreter.go +++ b/modules/runs/interpreter.go @@ -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 diff --git a/modules/runs/runs.go b/modules/runs/runs.go index 3b2a047f1..2e519833a 100644 --- a/modules/runs/runs.go +++ b/modules/runs/runs.go @@ -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) {