feat(controlplane): organisation forge connections

A connection is an organisation's own resource: the forge host, the
credential reference and the external account it belongs to. It records a
reference, never a token value, and names per execution identity the
operations that identity may perform through it.

The file's [forge] sections seed it: the root's becomes the root connection
and each identity's own forge becomes a connection only that identity may
use, so the migration keeps exactly the grants the file expressed.
This commit is contained in:
sam committed 2026-10-17 03:05:01 +11:00
1 parent 195644ed03
commit 5f99812299
8 files changed
+916 -389

No files matched your search

+10 -1
View File
@@ -220,11 +220,20 @@ func (s *Server) Watch(request *pb.WatchRequest, stream pb.ControlPlaneService_W
}
}
// orgSeededKinds are the kinds every organisation holds its own document of.
// Reading one an org has never written answers with the empty document: an
// org that has configured nothing has nothing, rather than the system org's
// configuration or a not-found the dashboard cannot tell from a failure.
var orgSeededKinds = map[string]bool{
WorkflowDefinitionsKind: true, WorkflowEnablementKind: true,
ForgeConnectionsKind: true,
}
// resource seeds an org's workflow documents on first use, including orgs
// created after this process started. File-derived settings are never copied.
func (s *Server) resource(ctx context.Context, orgID, kind string) (storecontract.Resource, error) {
resource, err := s.store.Resource(ctx, orgID, kind)
if !errors.Is(err, storecontract.ErrResourceNotFound) || (kind != WorkflowDefinitionsKind && kind != WorkflowEnablementKind) {
if !errors.Is(err, storecontract.ErrResourceNotFound) || !orgSeededKinds[kind] {
// Serve the current channel schema so stored settings remain editable.
if err == nil && kind == ChannelSettingsKind {
resource.Value, err = normalizeChannels(resource.Value)
+1 -1
View File
@@ -8,7 +8,7 @@ import (
// Schemas are not declared here: each Definition names its document type, and
// Definition.Descriptor derives the JSON Schema from it (internal/app/controlplane/schema.go).
func builtinDefinitions(steps workflow.StepRegistry, settings map[string]any) []Definition {
definitions := []Definition{taskPolicyDefinition(), workflowDefinition(), workflowDefinitionsDefinition(steps, settings), workflowEnablementDefinition(), curatorDefinition(), soulDefinition(), scheduleDefinition(), agentProfileDefinition(), playbooksDefinition(), skillsDefinition(), credentialBindingsDefinition(), identityGrantsDefinition(), reviewSettingsDefinition(), orgModelPolicyDefinition()}
definitions := []Definition{taskPolicyDefinition(), workflowDefinition(), workflowDefinitionsDefinition(steps, settings), workflowEnablementDefinition(), curatorDefinition(), soulDefinition(), scheduleDefinition(), agentProfileDefinition(), playbooksDefinition(), skillsDefinition(), credentialBindingsDefinition(), identityGrantsDefinition(), reviewSettingsDefinition(), orgModelPolicyDefinition(), forgeConnectionsDefinition()}
definitions = append(definitions, modelDefinitions()...)
definitions = append(definitions, operationalDefinitions()...)
return definitions
@@ -0,0 +1,128 @@
package controlplane
import (
"fmt"
"maps"
"slices"
"strings"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/identity"
)
// ForgeConnectionsKind is the resource holding an organisation's external
// forge connections. Its document is []config.ForgeConnection, the same shape
// the runtime resolves, so a stored connection and a resolved one cannot
// disagree about what a connection is.
const ForgeConnectionsKind = "forge-connections"
// rootConnectionID names the connection the file's [forge] section migrates
// into: the instance root's own account, used by root tasks.
const rootConnectionID = "default"
func forgeConnectionsDefinition() Definition {
return Definition{
Kind: ForgeConnectionsKind,
Title: "Forge connections",
ApplyMode: "live",
Document: []config.ForgeConnection{},
Seed: seedForgeConnections,
Validate: validateForgeConnections,
}
}
// seedForgeConnections migrates the file's forge configuration into
// connections: the root's [forge] becomes the root connection, and each
// identity that declared its own forge becomes that identity's connection.
// The permissions reproduce what the file already granted -- the root
// connection to root tasks, each identity's own forge to that identity -- so
// the migration neither widens nor narrows access. The file never recorded
// which external account a credential belongs to, so Account is seeded empty
// and is filled by a verification.
func seedForgeConnections(cfg config.Config) any {
out := []config.ForgeConnection{}
if c, ok := connectionFromForge(rootConnectionID, "Instance forge", cfg.Forge); ok {
// Root tasks act as the instance, not as an organisation execution
// identity, so they take this connection without a permit entry. An
// execution identity needs one, and the file granted it none.
out = append(out, c)
}
for _, id := range cfg.Identities {
c, ok := connectionFromForge("identity-"+id.Name, id.Name, id.Forge)
if !ok {
continue
}
// The file gave this identity its own credential and no limit on what
// it did with it; keeping that exact grant is what a migration owes.
c.Permits = map[string][]string{string(identity.StableID(id.Name)): config.Operations()}
out = append(out, c)
}
return out
}
// connectionFromForge reads one file forge section as a connection. A forge
// with no type is not configured and seeds nothing.
func connectionFromForge(id, name string, cfg config.Forge) (config.ForgeConnection, bool) {
if strings.TrimSpace(cfg.Type) == "" {
return config.ForgeConnection{}, false
}
return config.ForgeConnection{
ID: id, Name: name, Type: cfg.Type, Host: cfg.Host, Token: cfg.Token,
}, true
}
func validateForgeConnections(input []byte) error {
return validateAs(input, func(connections []config.ForgeConnection) error {
seen := make(map[string]struct{}, len(connections))
for _, c := range connections {
if err := validateForgeConnection(c); err != nil {
return err
}
if _, dup := seen[c.ID]; dup {
return fmt.Errorf("duplicate connection %q", c.ID)
}
seen[c.ID] = struct{}{}
}
return nil
})
}
func validateForgeConnection(c config.ForgeConnection) error {
// A slash would let an ID spell another resource's audit record key, the
// same reason resource keys refuse one.
if strings.TrimSpace(c.ID) == "" || strings.Contains(c.ID, "/") {
return fmt.Errorf("connection ID is required and may not contain %q", "/")
}
if strings.TrimSpace(c.Name) == "" {
return fmt.Errorf("connection %q needs a name", c.ID)
}
if strings.TrimSpace(c.Type) == "" {
return fmt.Errorf("connection %q needs a forge type", c.ID)
}
if strings.TrimSpace(c.Host) == "" {
return fmt.Errorf("connection %q needs a host", c.ID)
}
if (c.Token.Engine == "") != (c.Token.Key == "") {
return fmt.Errorf("connection %q: the credential reference needs both an engine and a key", c.ID)
}
for _, id := range slices.Sorted(maps.Keys(c.Permits)) {
operations := c.Permits[id]
if strings.TrimSpace(id) == "" {
return fmt.Errorf("connection %q: a permitted identity is empty", c.ID)
}
if len(operations) == 0 {
return fmt.Errorf("connection %q: identity %s is permitted nothing; remove the entry instead", c.ID, id)
}
seen := make(map[string]struct{}, len(operations))
for _, op := range operations {
if !config.ValidOperation(op) {
return fmt.Errorf("connection %q: identity %s: unknown operation %q (want clone, push or pr)", c.ID, id, op)
}
if _, dup := seen[op]; dup {
return fmt.Errorf("connection %q: identity %s lists %q twice", c.ID, id, op)
}
seen[op] = struct{}{}
}
}
return nil
}
@@ -0,0 +1,129 @@
package controlplane
import (
"encoding/json"
"errors"
"slices"
"testing"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/identity"
)
func TestForgeConnectionValidation(t *testing.T) {
tests := []struct {
name string
doc string
refused bool
}{
{
name: "a host, a credential reference and a permitted operation",
doc: `[{"id":"gh","name":"GitHub","type":"github","host":"github.com","token":{"engine":"env","key":"GH_TOKEN"},"permits":{"bot-1":["clone","push"]}}]`,
},
{
name: "a connection with no external account is still configurable",
doc: `[{"id":"gh","name":"GitHub","type":"github","host":"github.com"}]`,
},
{
name: "no host",
doc: `[{"id":"gh","name":"GitHub","type":"github"}]`,
refused: true,
},
{
name: "no forge type",
doc: `[{"id":"gh","name":"GitHub","host":"github.com"}]`,
refused: true,
},
{
name: "an ID that would spell another record key",
doc: `[{"id":"org-sys/gh","name":"GitHub","type":"github","host":"github.com"}]`,
refused: true,
},
{
name: "two connections claiming one ID",
doc: `[{"id":"gh","name":"GitHub","type":"github","host":"github.com"},{"id":"gh","name":"Other","type":"gitea","host":"gitea.example.com"}]`,
refused: true,
},
{
name: "half a credential reference",
doc: `[{"id":"gh","name":"GitHub","type":"github","host":"github.com","token":{"key":"GH_TOKEN"}}]`,
refused: true,
},
{
name: "an operation the runtime cannot perform",
doc: `[{"id":"gh","name":"GitHub","type":"github","host":"github.com","permits":{"bot-1":["clone","admin"]}}]`,
refused: true,
},
{
name: "the same operation twice",
doc: `[{"id":"gh","name":"GitHub","type":"github","host":"github.com","permits":{"bot-1":["push","push"]}}]`,
refused: true,
},
{
name: "an identity permitted nothing",
doc: `[{"id":"gh","name":"GitHub","type":"github","host":"github.com","permits":{"bot-1":[]}}]`,
refused: true,
},
{
name: "a connection with no name",
doc: `[{"id":"gh","type":"github","host":"github.com"}]`,
refused: true,
},
{
name: "a document that names a field the connection does not have",
doc: `[{"id":"gh","name":"GitHub","type":"github","host":"github.com","token_value":"ghp_literal"}]`,
refused: true,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
err := forgeConnectionsDefinition().Validate([]byte(tt.doc))
if refused := errors.Is(err, ErrValidation) || err != nil; refused != tt.refused {
t.Fatalf("refused = %v, want %v (err %v)", refused, tt.refused, err)
}
})
}
}
// TestConnectionMigrationKeepsTheFilesGrants is the migration's security
// claim: what the file granted, the connections grant, and nothing more. The
// root connection takes no permit entry, so no execution identity reaches it;
// each identity's own forge becomes a connection only that identity may use.
func TestConnectionMigrationKeepsTheFilesGrants(t *testing.T) {
cfg := config.Config{
Forge: config.Forge{Type: "github", Host: "github.com", Token: config.SecretRef{Engine: "env", Key: "ROOT_TOKEN"}},
Identities: []config.IdentityConfig{
{Name: "reviewer", Forge: config.Forge{Type: "github", Host: "github.com", Token: config.SecretRef{Engine: "env", Key: "REVIEWER_TOKEN"}}},
{Name: "silent"},
},
}
seeded, err := forgeConnectionsDefinition().seededValue(cfg)
if err != nil {
t.Fatalf("seed: %v", err)
}
var connections []config.ForgeConnection
if err := json.Unmarshal(seeded, &connections); err != nil {
t.Fatalf("decode seed: %v", err)
}
if len(connections) != 2 {
t.Fatalf("seeded %d connections, want the root's and the one identity that declared a forge: %+v", len(connections), connections)
}
root, reviewer := connections[0], connections[1]
if root.ID != rootConnectionID || len(root.Permits) != 0 {
t.Fatalf("root connection = %+v, want the root's forge and no permitted execution identity", root)
}
if root.Token.Key != "ROOT_TOKEN" {
t.Fatalf("root connection credential = %+v, want the file's reference", root.Token)
}
if reviewer.ID != "identity-reviewer" {
t.Fatalf("second connection = %q, want the declaring identity's", reviewer.ID)
}
if permitted := reviewer.Permits[string(identity.StableID("reviewer"))]; !slices.Equal(permitted, config.Operations()) {
t.Fatalf("reviewer permits = %v, want every operation it already had (%v)", permitted, config.Operations())
}
for id := range reviewer.Permits {
if id != string(identity.StableID("reviewer")) {
t.Fatalf("reviewer connection permits %q as well; an identity with no forge of its own must not gain one", id)
}
}
}
@@ -15,6 +15,7 @@ func TestInstanceOnlyKindsRefuseOtherOrgs(t *testing.T) {
{"another org writes an instance setting", "acme", ToolSettingsKind, true},
{"the system org writes an instance setting", storecontract.DefaultOrgID, ToolSettingsKind, false},
{"another org writes an org-scoped kind", "acme", SoulKind, false},
{"another org writes a forge connection", "acme", ForgeConnectionsKind, false},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
+60 -3
View File
@@ -7,9 +7,11 @@ import (
"fmt"
"maps"
"net"
"slices"
"strings"
"time"
"github.com/samcharles93/archie-core/internal/domain/identity"
orgdomain "github.com/samcharles93/archie-core/internal/domain/org"
)
@@ -41,10 +43,61 @@ func (d *Duration) UnmarshalJSON(data []byte) error {
func (d Duration) Std() time.Duration { return time.Duration(d) }
// The operations an execution identity may be permitted through a forge
// connection. Read-only is the clone; a task that writes asks for push, and
// one that opens or updates a pull request asks for pr.
const (
OperationClone = "clone"
OperationPush = "push"
OperationPR = "pr"
)
// Operations is every operation, in vocabulary order.
func Operations() []string { return []string{OperationClone, OperationPush, OperationPR} }
// ValidOperation reports whether op is one of the shipped operations.
func ValidOperation(op string) bool { return slices.Contains(Operations(), op) }
// ForgeConnection is one organisation-owned connection to a forge: where it
// is, how to authenticate and which external account that authentication
// belongs to. It is the organisation's own resource, not a copy of the
// instance's root configuration.
type ForgeConnection struct {
// ID is the stable reference a repository binding and a permission name.
ID string `toml:"id" json:"id" yaml:"id"`
// Name is the operator-facing label.
Name string `toml:"name" json:"name" yaml:"name"`
// Type selects the forge implementation: the name of an enabled forge
// extension, or the compiled-in forge of that name.
Type string `toml:"type" json:"type" yaml:"type"`
// Host is the forge's host, e.g. "github.com".
Host string `toml:"host" json:"host" yaml:"host"`
// Account is the external account the credential authenticates as. It is
// recorded, and checked against the account a verification actually
// reached; it is never used to infer authority.
Account string `toml:"account" json:"account" yaml:"account"`
// Token references the credential. The connection records the reference,
// never a token value.
Token SecretRef `toml:"token" json:"token" yaml:"token"`
// Permits names, per execution identity ID, the operations that identity
// may perform through this connection. An identity with no entry may
// perform none: the connection itself is not a grant.
Permits map[string][]string `toml:"permits" json:"permits,omitempty" yaml:"permits"`
}
// Permitted reports whether the identity may perform op through this
// connection.
func (c ForgeConnection) Permitted(identityID, op string) bool {
return slices.Contains(c.Permits[identityID], op)
}
// Repo is one managed repository.
type Repo struct {
Owner string `toml:"owner" json:"owner" yaml:"owner"`
Name string `toml:"name" json:"name" yaml:"name"`
// Connection names the ForgeConnection this repository is reached
// through. Empty is a repository the instance's root forge owns.
Connection string `toml:"connection" json:"connection" yaml:"connection"`
// Base is the branch PRs target. Defaults to "main".
Base string `toml:"base" json:"base" yaml:"base"`
// Gate is the repo's gate command list, e.g. [["go","vet","./..."],
@@ -731,11 +784,14 @@ func (c ContainerConfig) BoundCredentials(org string, granted, declared []string
// CredentialAccess returns the org and granted credential services of the
// identity named name: the root's, each overridden by the identity's own when
// it sets one. An unknown name is the root.
// it sets one. Unknown identities receive no grants.
func (c Config) CredentialAccess(name string) (org string, granted []string) {
org, granted = c.Org, c.GrantedCredentials
if name == "" {
return credentialOrg(org), granted
}
for _, id := range c.Identities {
if id.Name != name {
if id.Name != name && string(identity.StableID(id.Name)) != name {
continue
}
if id.Org != "" {
@@ -744,8 +800,9 @@ func (c Config) CredentialAccess(name string) (org string, granted []string) {
if id.GrantedCredentials != nil {
granted = *id.GrantedCredentials
}
return credentialOrg(org), granted
}
return credentialOrg(org), granted
return credentialOrg(org), nil
}
func credentialOrg(value string) string {
File diff suppressed because it is too large. Load diff
@@ -167,6 +167,7 @@ const (
StateStoreService_ListMembers_FullMethodName = "/state.v1.StateStoreService/ListMembers"
StateStoreService_SetMembership_FullMethodName = "/state.v1.StateStoreService/SetMembership"
StateStoreService_RemoveMembership_FullMethodName = "/state.v1.StateStoreService/RemoveMembership"
StateStoreService_ListOrgAgents_FullMethodName = "/state.v1.StateStoreService/ListOrgAgents"
StateStoreService_AssignAgent_FullMethodName = "/state.v1.StateStoreService/AssignAgent"
StateStoreService_RaiseAlert_FullMethodName = "/state.v1.StateStoreService/RaiseAlert"
StateStoreService_ResolveAlert_FullMethodName = "/state.v1.StateStoreService/ResolveAlert"
@@ -450,6 +451,7 @@ type StateStoreServiceClient interface {
ListMembers(ctx context.Context, in *ListMembersRequest, opts ...grpc.CallOption) (*ListMembersResponse, error)
SetMembership(ctx context.Context, in *SetMembershipRequest, opts ...grpc.CallOption) (*SetMembershipResponse, error)
RemoveMembership(ctx context.Context, in *RemoveMembershipRequest, opts ...grpc.CallOption) (*RemoveMembershipResponse, error)
ListOrgAgents(ctx context.Context, in *ListOrgAgentsRequest, opts ...grpc.CallOption) (*ListOrgAgentsResponse, error)
AssignAgent(ctx context.Context, in *AssignAgentRequest, opts ...grpc.CallOption) (*AssignAgentResponse, error)
// Operator alerts (internal/domain/alert). A caller acting for a principal
// reads, dismisses and raises only in that principal's org; a request org is
@@ -1980,6 +1982,16 @@ func (c *stateStoreServiceClient) RemoveMembership(ctx context.Context, in *Remo
return out, nil
}
func (c *stateStoreServiceClient) ListOrgAgents(ctx context.Context, in *ListOrgAgentsRequest, opts ...grpc.CallOption) (*ListOrgAgentsResponse, error) {
cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
out := new(ListOrgAgentsResponse)
err := c.cc.Invoke(ctx, StateStoreService_ListOrgAgents_FullMethodName, in, out, cOpts...)
if err != nil {
return nil, err
}
return out, nil
}
func (c *stateStoreServiceClient) AssignAgent(ctx context.Context, in *AssignAgentRequest, opts ...grpc.CallOption) (*AssignAgentResponse, error) {
cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
out := new(AssignAgentResponse)
@@ -2324,6 +2336,7 @@ type StateStoreServiceServer interface {
ListMembers(context.Context, *ListMembersRequest) (*ListMembersResponse, error)
SetMembership(context.Context, *SetMembershipRequest) (*SetMembershipResponse, error)
RemoveMembership(context.Context, *RemoveMembershipRequest) (*RemoveMembershipResponse, error)
ListOrgAgents(context.Context, *ListOrgAgentsRequest) (*ListOrgAgentsResponse, error)
AssignAgent(context.Context, *AssignAgentRequest) (*AssignAgentResponse, error)
// Operator alerts (internal/domain/alert). A caller acting for a principal
// reads, dismisses and raises only in that principal's org; a request org is
@@ -2791,6 +2804,9 @@ func (UnimplementedStateStoreServiceServer) SetMembership(context.Context, *SetM
func (UnimplementedStateStoreServiceServer) RemoveMembership(context.Context, *RemoveMembershipRequest) (*RemoveMembershipResponse, error) {
return nil, status.Error(codes.Unimplemented, "method RemoveMembership not implemented")
}
func (UnimplementedStateStoreServiceServer) ListOrgAgents(context.Context, *ListOrgAgentsRequest) (*ListOrgAgentsResponse, error) {
return nil, status.Error(codes.Unimplemented, "method ListOrgAgents not implemented")
}
func (UnimplementedStateStoreServiceServer) AssignAgent(context.Context, *AssignAgentRequest) (*AssignAgentResponse, error) {
return nil, status.Error(codes.Unimplemented, "method AssignAgent not implemented")
}
@@ -5476,6 +5492,24 @@ func _StateStoreService_RemoveMembership_Handler(srv interface{}, ctx context.Co
return interceptor(ctx, in, info, handler)
}
func _StateStoreService_ListOrgAgents_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
in := new(ListOrgAgentsRequest)
if err := dec(in); err != nil {
return nil, err
}
if interceptor == nil {
return srv.(StateStoreServiceServer).ListOrgAgents(ctx, in)
}
info := &grpc.UnaryServerInfo{
Server: srv,
FullMethod: StateStoreService_ListOrgAgents_FullMethodName,
}
handler := func(ctx context.Context, req interface{}) (interface{}, error) {
return srv.(StateStoreServiceServer).ListOrgAgents(ctx, req.(*ListOrgAgentsRequest))
}
return interceptor(ctx, in, info, handler)
}
func _StateStoreService_AssignAgent_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
in := new(AssignAgentRequest)
if err := dec(in); err != nil {
@@ -6189,6 +6223,10 @@ var StateStoreService_ServiceDesc = grpc.ServiceDesc{
MethodName: "RemoveMembership",
Handler: _StateStoreService_RemoveMembership_Handler,
},
{
MethodName: "ListOrgAgents",
Handler: _StateStoreService_ListOrgAgents_Handler,
},
{
MethodName: "AssignAgent",
Handler: _StateStoreService_AssignAgent_Handler,