Merge branch 'worktree-agent-a82ec64b6cc1a2809'

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

No files matched your search

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