From 33f7ebdff48b152c074144d2c29dc63031e03c73 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sun, 22 Nov 2026 23:03:01 +1100 Subject: [PATCH] feat: add member candidates endpoint and approvals page - serve active identities outside the org at /api/orgs/{id}/member-candidates and back the members page from it - add an org approvals page for default owner, deadline and escalation path over /api/settings --- api/openapi.yaml | 56 +++++++++ modules/governance/members_api.go | 42 +++++++ modules/governance/members_api_test.go | 70 ++++++++++- modules/governance/store_identities.go | 14 +++ ui/pages/pages.json | 5 + ui/src/lib/api.ts | 22 ++++ ui/src/lib/nav.ts | 2 +- ui/src/org/OrgApprovalsPage.vue | 167 +++++++++++++++++++++++++ ui/src/org/OrgMembersPage.vue | 28 ++--- ui/src/org/org.ts | 7 ++ ui/src/router/routes.ts | 7 ++ 11 files changed, 398 insertions(+), 22 deletions(-) create mode 100644 ui/src/org/OrgApprovalsPage.vue diff --git a/api/openapi.yaml b/api/openapi.yaml index d5dc891ea..e671b42d1 100644 --- a/api/openapi.yaml +++ b/api/openapi.yaml @@ -1833,6 +1833,18 @@ components: - to - reason type: object + GovernanceCandidatesBody: + additionalProperties: false + properties: + identities: + items: + $ref: "#/components/schemas/GovernanceMemberCandidate" + type: + - array + - "null" + required: + - identities + type: object GovernanceCapabilitiesBody: additionalProperties: false properties: @@ -2021,6 +2033,23 @@ components: - role - status type: object + GovernanceMemberCandidate: + additionalProperties: false + properties: + display_name: + description: Name shown for the identity + type: string + id: + description: Identity ID + type: string + kind: + description: Identity kind + type: string + required: + - id + - kind + - display_name + type: object GovernanceMembersBody: additionalProperties: false properties: @@ -7089,6 +7118,33 @@ paths: summary: List the organisation's name changes tags: - Organisations + /api/orgs/{id}/member-candidates: + get: + operationId: list-org-member-candidates + parameters: + - description: Organisation ID + in: path + name: id + required: true + schema: + description: Organisation ID + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/GovernanceCandidatesBody" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: List active identities that can be added as members + tags: + - Access /api/orgs/{id}/members: get: operationId: list-org-members diff --git a/modules/governance/members_api.go b/modules/governance/members_api.go index 904062fe6..76c6c9769 100644 --- a/modules/governance/members_api.go +++ b/modules/governance/members_api.go @@ -20,6 +20,7 @@ type memberDirectory interface { EnsureMembership(context.Context, Membership) error RemoveMembership(context.Context, Membership) error Get(context.Context, IdentityID) (Identity, error) + ListInstanceIdentities(context.Context) ([]Identity, error) Apply(context.Context, IdentityID, int64, IdentityCommand, IdentityAudit) (Identity, error) } @@ -51,6 +52,17 @@ type membersBody struct { Members []Member `json:"members"` } +// memberCandidate is the part of an identity needed to choose it as a member. +type memberCandidate struct { + ID IdentityID `json:"id" doc:"Identity ID"` + Kind Kind `json:"kind" doc:"Identity kind"` + DisplayName string `json:"display_name" doc:"Name shown for the identity"` +} + +type candidatesBody struct { + Identities []memberCandidate `json:"identities"` +} + type membershipBody struct { Membership Membership `json:"membership"` } @@ -98,6 +110,7 @@ func (m *Module) RegisterAccess(api huma.API) { } a := m.members() httpapi.Register(api, httpapi.Authorized(ActionRead, KindMember), op("list-org-members", http.MethodGet, "/api/orgs/{id}/members", "List an organisation's members", 0), a.list) + httpapi.Register(api, httpapi.Authorized(ActionManageMembers, KindMember), op("list-org-member-candidates", http.MethodGet, "/api/orgs/{id}/member-candidates", "List active identities that can be added as members", 0), a.candidates) httpapi.Register(api, httpapi.Authorized(ActionManageMembers, KindMember), op("add-org-member", http.MethodPost, "/api/orgs/{id}/members", "Add a person by email or provider subject", http.StatusCreated), a.add) httpapi.Register(api, httpapi.Authorized(ActionManageMembers, KindMember), op("set-org-member", http.MethodPut, "/api/orgs/{id}/members/{identity}", "Give a member a role", 0), a.set) httpapi.Register(api, httpapi.Authorized(ActionManageMembers, KindMember), op("remove-org-member", http.MethodDelete, "/api/orgs/{id}/members/{identity}", "Remove a membership", http.StatusNoContent), a.remove) @@ -118,6 +131,35 @@ func (a *memberAPI) list(ctx context.Context, in *orgPath) (*httpapi.Reply[membe return httpapi.OK(membersBody{Members: values}), nil } +// candidates lists the instance's active identities that have no +// organisation-wide membership. These are the identities offered when adding a +// member. +// The system identity is excluded because it cannot be a member. +func (a *memberAPI) candidates(ctx context.Context, in *orgPath) (*httpapi.Reply[candidatesBody], error) { + if _, err := actingOrg(ctx, OrgID(in.ID)); err != nil { + return nil, err + } + members, err := a.dir.ListMembers(ctx, OrgID(in.ID)) + if err != nil { + return nil, a.failed(ctx, "read the members", err) + } + all, err := a.dir.ListInstanceIdentities(ctx) + if err != nil { + return nil, a.failed(ctx, "read the identities", err) + } + out := make([]memberCandidate, 0, len(all)) + for _, value := range all { + if value.Kind == KindSystem || value.Lifecycle != LifecycleActive { + continue + } + if _, held := roleHeld(members, value.ID, ""); held { + continue + } + out = append(out, memberCandidate{ID: value.ID, Kind: value.Kind, DisplayName: value.DisplayName}) + } + return httpapi.OK(candidatesBody{Identities: out}), nil +} + func (a *memberAPI) set(ctx context.Context, in *setMemberInput) (*httpapi.Reply[membershipBody], error) { org, target := OrgID(in.ID), IdentityID(in.Identity) p, err := actingOrg(ctx, org) diff --git a/modules/governance/members_api_test.go b/modules/governance/members_api_test.go index f9e8e85bf..4c5c37bf8 100644 --- a/modules/governance/members_api_test.go +++ b/modules/governance/members_api_test.go @@ -5,6 +5,7 @@ import ( "errors" "log/slog" "net/http" + "slices" "strings" "testing" @@ -15,8 +16,9 @@ import ( // fakeDirectory records the changes a member route lets through. type fakeDirectory struct { - members []Member - changes []string + members []Member + identities []Identity + changes []string } func (f *fakeDirectory) ListMembers(context.Context, OrgID) ([]Member, error) { return f.members, nil } @@ -35,6 +37,10 @@ func (f *fakeDirectory) Get(_ context.Context, id IdentityID) (Identity, error) return Identity{ID: id, Version: 1}, nil } +func (f *fakeDirectory) ListInstanceIdentities(context.Context) ([]Identity, error) { + return f.identities, nil +} + func (f *fakeDirectory) Apply(_ context.Context, id IdentityID, _ int64, c IdentityCommand, _ IdentityAudit) (Identity, error) { f.changes = append(f.changes, string(c.Type)+" "+string(id)) return Identity{ID: id}, nil @@ -83,6 +89,7 @@ func TestAccessWritesNeedTheirGrant(t *testing.T) { writes := 0 for _, route := range httpapi.Routes(api) { mutates := route.Method != http.MethodGet + candidates := route.ID == "list-org-member-candidates" action, kind, ok := route.Access.Declared() if !ok { t.Errorf("%s declares no access", route.ID) @@ -95,7 +102,7 @@ func TestAccessWritesNeedTheirGrant(t *testing.T) { if strings.HasPrefix(route.Path, "/api/access/policies") { wantAction = string(ActionManagePolicies) } - if mutates && action != wantAction { + if (mutates || candidates) && action != wantAction { t.Errorf("%s declares %q, want %q", route.ID, action, wantAction) } if !mutates && route.Path == "/api/access/denials" && action != string(ActionReadAudit) { @@ -105,7 +112,7 @@ func TestAccessWritesNeedTheirGrant(t *testing.T) { if !engine.Authorize(t.Context(), actor("admin", RoleAdmin), Action(action), resource, AccessContext{}).Allowed { t.Errorf("%s: an admin is refused %s %s", route.ID, action, kind) } - if mutates || route.Path == "/api/access/denials" { + if mutates || candidates || route.Path == "/api/access/denials" { for _, role := range []Role{RoleViewer, RoleDeveloper} { if engine.Authorize(t.Context(), actor("lowly", role), Action(action), resource, AccessContext{}).Allowed { t.Errorf("%s: a %s is allowed %s %s", route.ID, role, action, kind) @@ -118,6 +125,61 @@ func TestAccessWritesNeedTheirGrant(t *testing.T) { } } +// TestMemberCandidates guards the listing offered when adding a member: it is +// limited to active identities outside the organisation, never reaches another +// organisation, and never offers the system identity. +func TestMemberCandidates(t *testing.T) { + identities := []Identity{ + {ID: "root", Kind: KindUser, DisplayName: "Root", Lifecycle: LifecycleActive}, + {ID: "newcomer", Kind: KindUser, DisplayName: "Newcomer", Lifecycle: LifecycleActive}, + {ID: "scoped", Kind: KindUser, DisplayName: "Scoped", Lifecycle: LifecycleActive}, + {ID: "gone", Kind: KindUser, DisplayName: "Gone", Lifecycle: LifecycleSuspended}, + {ID: SystemID, Kind: KindSystem, DisplayName: "System", Lifecycle: LifecycleActive}, + } + members := []Member{ + member("root", RoleOwner, LifecycleActive), + {IdentityID: "scoped", Kind: KindUser, WorkspaceID: "ws", Role: RoleViewer, Status: LifecycleActive}, + } + foreign := actor("outsider", RoleOwner) + foreign.Org = "other" + foreign.Memberships = []Membership{{IdentityID: "outsider", OrgID: "other", Role: RoleOwner}} + tests := []struct { + name string + by *Principal + org OrgID + want int + ids []IdentityID + }{ + {"owner sees identities outside the org", new(actor("root", RoleOwner)), DefaultOrgID, http.StatusOK, []IdentityID{"newcomer", "scoped"}}, + {"member of another org", &foreign, DefaultOrgID, http.StatusNotFound, nil}, + {"owner of another org asks for its own org", &foreign, "other", http.StatusOK, []IdentityID{"newcomer", "scoped"}}, + {"caller without a session", nil, DefaultOrgID, http.StatusUnauthorized, nil}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + dir := &fakeDirectory{members: members, identities: identities} + ctx := t.Context() + if tt.by != nil { + ctx = WithPrincipal(ctx, *tt.by) + } + reply, err := memberRoutes(dir).candidates(ctx, &orgPath{ID: string(tt.org)}) + if got := status(t, err); got != tt.want { + t.Fatalf("status = %d (%v), want %d", got, err, tt.want) + } + if err != nil { + return + } + var got []IdentityID + for _, c := range reply.Body.Identities { + got = append(got, c.ID) + } + if !slices.Equal(got, tt.ids) { + t.Fatalf("candidates = %v, want %v", got, tt.ids) + } + }) + } +} + // TestLastOwnerIsKept guards the rule that an organisation always keeps an // active owner: removing, demoting or suspending the only one is refused before // anything changes. diff --git a/modules/governance/store_identities.go b/modules/governance/store_identities.go index 72dbab47c..886954991 100644 --- a/modules/governance/store_identities.go +++ b/modules/governance/store_identities.go @@ -115,6 +115,20 @@ func (m *Module) List(ctx context.Context) ([]Identity, error) { return out, nil } +// ListInstanceIdentities returns every identity on the instance, regardless of +// the caller's organisation scope. +func (m *Module) ListInstanceIdentities(ctx context.Context) ([]Identity, error) { + rows, err := m.store.ListIdentities(ctx, nil) + if err != nil { + return nil, err + } + out := make([]Identity, 0, len(rows)) + for _, r := range rows { + out = append(out, identityFromRow(r)) + } + return out, nil +} + // Get returns one identity by ID if visible to the caller's scope. func (m *Module) Get(ctx context.Context, id IdentityID) (Identity, error) { row, err := m.store.GetVisibleIdentity(ctx, string(id), scopeOrgFilter(ctx)) diff --git a/ui/pages/pages.json b/ui/pages/pages.json index cdf7da59c..50c77190e 100644 --- a/ui/pages/pages.json +++ b/ui/pages/pages.json @@ -144,6 +144,11 @@ "label": "Models", "description": "The organisation's agent models and aliases." }, + { + "path": "/org/approvals", + "label": "Approvals", + "description": "Default owner, escalation path and approval deadline." + }, { "path": "/org/instructions", "label": "Instructions", diff --git a/ui/src/lib/api.ts b/ui/src/lib/api.ts index c1615edbe..10b2394ec 100644 --- a/ui/src/lib/api.ts +++ b/ui/src/lib/api.ts @@ -288,6 +288,9 @@ export const api = { credentialKinds: () => request("/api/credential-kinds"), putCredential: (name: string, kind: string, fields: Record) => request<{ name: string; kind: string; restarted: string[] }>(`/api/credentials/${encodeURIComponent(name)}`, { method: "PUT", body: { kind, fields }, timeoutMs: 60_000 }), + orgSettings: () => request("/api/settings"), + putOrgSettings: (settings: OrgSettings) => + request("/api/settings", { method: "PUT", body: settings }), instructions: () => request<{ text: string }>("/api/settings/instructions"), saveInstructions: (text: string) => request<{ text: string }>("/api/settings/instructions", { method: "PUT", body: { text } }), @@ -412,6 +415,8 @@ export const api = { orgAgents: (id: string) => request(`/api/orgs/${encodeURIComponent(id)}/agents`), orgMembers: (id: string) => request(`/api/orgs/${encodeURIComponent(id)}/members`), + orgMemberCandidates: (id: string) => + request(`/api/orgs/${encodeURIComponent(id)}/member-candidates`), addOrgMember: ( id: string, member: { subject?: string; email?: string; role: string }, @@ -1205,6 +1210,23 @@ export interface ExtensionInput { effects?: ServerEffects; } +/** One stop on the escalation path; the deadline is a Go duration string. */ +export interface EscalationStep { + account: string; + deadline: string; +} + +/** + * The organisation settings. The server replaces all of them on save, so a page + * that edits some sends back the rest as it read them. + */ +export interface OrgSettings { + approval_deadline: string; + default_owner: string; + escalation: EscalationStep[]; + [other: string]: unknown; +} + export interface Credential { name: string; kind: string; diff --git a/ui/src/lib/nav.ts b/ui/src/lib/nav.ts index cc2d1982a..772ddfdcf 100644 --- a/ui/src/lib/nav.ts +++ b/ui/src/lib/nav.ts @@ -35,7 +35,7 @@ const orgSpecs: NavSpec[] = [ sections: [ { label: "People & access", - paths: ["/org/members", "/org/agents", "/org/workspaces", "/org/policies", "/org/denials", "/org/audit"], + paths: ["/org/members", "/org/approvals", "/org/agents", "/org/workspaces", "/org/policies", "/org/denials", "/org/audit"], }, { label: "Agents", diff --git a/ui/src/org/OrgApprovalsPage.vue b/ui/src/org/OrgApprovalsPage.vue new file mode 100644 index 000000000..e5cd3f73a --- /dev/null +++ b/ui/src/org/OrgApprovalsPage.vue @@ -0,0 +1,167 @@ + + + diff --git a/ui/src/org/OrgMembersPage.vue b/ui/src/org/OrgMembersPage.vue index a737d6623..ce1e529ea 100644 --- a/ui/src/org/OrgMembersPage.vue +++ b/ui/src/org/OrgMembersPage.vue @@ -6,7 +6,7 @@ import PageHeader from "@/base/PageHeader.vue"; import CreateAccount from "@/accounts/CreateAccount.vue"; import { Section } from "@/components/ui/section"; import { storeToRefs } from "pinia"; -import { computed, onMounted, ref } from "vue"; +import { onMounted, ref } from "vue"; import { Pause, Play, Plus, Trash2 } from "@lucide/vue"; import { Badge } from "@/components/ui/badge"; @@ -33,7 +33,7 @@ import { import { api, describeError } from "@/lib/api"; import { errors } from "@/copy/errors"; import { useOrgStore } from "@/stores/org"; -import { ROLE_LABELS, ROLES, type Member, type Role } from "./org"; +import { ROLE_LABELS, ROLES, type Candidate, type Member, type Role } from "./org"; /** * The org's members and the role each holds. A membership is org-wide, or @@ -41,6 +41,7 @@ import { ROLE_LABELS, ROLES, type Member, type Role } from "./org"; * a member touches exactly that membership. */ const members = ref([]); +const candidates = ref([]); const error = ref(""); const loading = ref(true); const busy = ref(""); @@ -57,9 +58,14 @@ const personRole = ref("viewer"); async function load(): Promise { if (!org.value) return; try { - members.value = ( - await api.orgMembers<{ members: Member[] }>(org.value.id) - ).members; + const id = org.value.id; + const [list, offered] = await Promise.all([ + api.orgMembers<{ members: Member[] }>(id), + api.orgMemberCandidates<{ identities: Candidate[] }>(id), + ]); + if (org.value?.id !== id) return; + members.value = list.members; + candidates.value = offered.identities; error.value = ""; } catch (cause) { error.value = describeError(cause, errors.common.unknown); @@ -69,7 +75,6 @@ async function load(): Promise { onMounted(async () => { try { await identities.loadOrg(); - identities.watchIdentities(); await load(); } catch (cause) { error.value = describeError(cause, errors.common.unknown); @@ -78,17 +83,6 @@ onMounted(async () => { } }); -// Active identities that hold no org-wide membership yet, so Add cannot pick -// someone the table already shows. The system identity is not a person. -const candidates = computed(() => { - const taken = new Set( - members.value.filter((m) => !m.workspace_id).map((m) => m.identity_id), - ); - return identities.identities.filter( - (i) => i.kind !== "system" && i.lifecycle === "active" && !taken.has(i.id), - ); -}); - async function run(key: string, action: () => Promise): Promise { busy.value = key; try { diff --git a/ui/src/org/org.ts b/ui/src/org/org.ts index 6373258a6..3ce42b121 100644 --- a/ui/src/org/org.ts +++ b/ui/src/org/org.ts @@ -41,6 +41,13 @@ export const ROLE_LABELS: Record = { viewer: "Viewer", }; +/** An identity that can be added to the org as a member. */ +export interface Candidate { + id: string; + kind: string; + display_name: string; +} + export interface Member { identity_id: string; kind: string; diff --git a/ui/src/router/routes.ts b/ui/src/router/routes.ts index 7046636b1..f42715c29 100644 --- a/ui/src/router/routes.ts +++ b/ui/src/router/routes.ts @@ -18,6 +18,7 @@ const OrgAccessPage = () => import("@/org/OrgAccessPage.vue"); const OrgUsagePage = () => import("@/org/OrgUsagePage.vue"); const SchedulingPolicyPage = () => import("@/settings/SchedulingPolicyPage.vue"); const ToolsPage = () => import("@/settings/ToolsPage.vue"); +const OrgApprovalsPage = () => import("@/org/OrgApprovalsPage.vue"); const InstructionsPage = () => import("@/settings/InstructionsPage.vue"); const ExtensionsPage = () => import("@/settings/ExtensionsPage.vue"); const PluginsPage = () => import("@/settings/PluginsPage.vue"); @@ -325,6 +326,12 @@ export const routes: RouteRecordRaw[] = [ redirect: "/settings/models", meta: { section: "org_config", label: "Models", navPath: "/org", description: "The organisation's agent models and aliases." }, }, + { + path: "approvals", + name: "org-approvals", + component: OrgApprovalsPage, + meta: { section: "org_config", label: "Approvals", navPath: "/org", description: "Default owner, escalation path and approval deadline." }, + }, { path: "instructions", name: "org-instructions",