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
This commit is contained in:
sam committed 2026-11-22 23:03:01 +11:00
1 parent e801306c15
commit 33f7ebdff4
11 files changed
+398 -22

No files matched your search

+56
View File
@@ -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
+42
View File
@@ -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)
+66 -4
View File
@@ -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.
+14
View File
@@ -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))
+5
View File
@@ -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",
+22
View File
@@ -288,6 +288,9 @@ export const api = {
credentialKinds: () => request<CredentialKind[]>("/api/credential-kinds"),
putCredential: (name: string, kind: string, fields: Record<string, CredentialField>) =>
request<{ name: string; kind: string; restarted: string[] }>(`/api/credentials/${encodeURIComponent(name)}`, { method: "PUT", body: { kind, fields }, timeoutMs: 60_000 }),
orgSettings: () => request<OrgSettings>("/api/settings"),
putOrgSettings: (settings: OrgSettings) =>
request<OrgSettings>("/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: <T = unknown>(id: string) => request<T>(`/api/orgs/${encodeURIComponent(id)}/agents`),
orgMembers: <T = unknown>(id: string) =>
request<T>(`/api/orgs/${encodeURIComponent(id)}/members`),
orgMemberCandidates: <T = unknown>(id: string) =>
request<T>(`/api/orgs/${encodeURIComponent(id)}/member-candidates`),
addOrgMember: <T = unknown>(
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;
+1 -1
View File
@@ -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",
+167
View File
@@ -0,0 +1,167 @@
<script setup lang="ts">
import { Plus, Trash2 } from "@lucide/vue";
import { computed, onMounted, ref } from "vue";
import { storeToRefs } from "pinia";
import PageHeader from "@/base/PageHeader.vue";
import { Alert, AlertDescription } from "@/components/ui/alert";
import { Button } from "@/components/ui/button";
import { DurationInput } from "@/components/ui/duration-input";
import { ReadError } from "@/components/ui/read-error";
import { Section } from "@/components/ui/section";
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
import { SettingRow } from "@/components/ui/setting-row";
import { errors } from "@/copy/errors";
import { api, describeError, type OrgSettings } from "@/lib/api";
import { useOrgStore } from "@/stores/org";
import type { Member } from "./org";
// The select has no empty option value, so "no default owner" is this marker.
const NONE = "none";
// Default deadline for a new step. The server accepts one minute to 30 days.
const NEW_STEP_DEADLINE = "4h";
interface Draft {
approval_deadline: string;
default_owner: string;
escalation: { account: string; deadline: string }[];
}
const orgStore = useOrgStore();
const { org } = storeToRefs(orgStore);
const saved = ref<OrgSettings | null>(null);
const people = ref<Member[]>([]);
const draft = ref<Draft | null>(null);
const loadError = ref("");
const saveError = ref("");
const busy = ref(false);
// Only people with an org-wide membership can approve; the server rejects anyone else.
const eligible = computed(() => people.value.filter((member) => member.kind === "user" && !member.workspace_id));
const nameOf = (id: string) => eligible.value.find((member) => member.identity_id === id)?.display_name ?? id;
function toDraft(settings: OrgSettings): Draft {
return {
approval_deadline: settings.approval_deadline,
default_owner: settings.default_owner,
escalation: settings.escalation.map((step) => ({ ...step })),
};
}
const dirty = computed(() => saved.value !== null && JSON.stringify(draft.value) !== JSON.stringify(toDraft(saved.value)));
async function load(): Promise<void> {
loadError.value = "";
try {
await orgStore.loadOrg();
if (!org.value) return;
const [settings, members] = await Promise.all([api.orgSettings(), api.orgMembers<{ members: Member[] }>(org.value.id)]);
people.value = members.members;
saved.value = settings;
draft.value = toDraft(settings);
} catch (cause) {
loadError.value = describeError(cause, errors.common.unknown);
}
}
// A person can appear on the path only once, so each step offers its current
// selection plus the people not used by other steps.
function choices(account: string) {
const taken = new Set(draft.value?.escalation.map((step) => step.account));
return eligible.value.filter((member) => member.identity_id === account || !taken.has(member.identity_id));
}
const canAdd = computed(() => draft.value !== null && choices("").length > 0);
function addStep(): void {
const next = choices("")[0];
if (draft.value && next) draft.value.escalation.push({ account: next.identity_id, deadline: NEW_STEP_DEADLINE });
}
async function save(): Promise<void> {
if (!saved.value || !draft.value || busy.value) return;
busy.value = true;
saveError.value = "";
try {
const updated = await api.putOrgSettings({ ...saved.value, ...draft.value });
saved.value = updated;
draft.value = toDraft(updated);
} catch (cause) {
saveError.value = describeError(cause, errors.common.unknown);
} finally {
busy.value = false;
}
}
onMounted(load);
</script>
<template>
<div>
<PageHeader title="Approvals" />
<ReadError v-if="loadError" :message="loadError" retry-label="Retry" @retry="load" />
<form v-else-if="draft" @submit.prevent="save">
<Section>
<SettingRow label="Default owner" for="approvals-owner">
<Select
:model-value="draft.default_owner || NONE"
@update:model-value="draft.default_owner = $event === NONE ? '' : String($event)"
>
<SelectTrigger id="approvals-owner" class="w-64">
<SelectValue />
</SelectTrigger>
<SelectContent>
<SelectItem :value="NONE">None</SelectItem>
<SelectItem v-for="member in eligible" :key="member.identity_id" :value="member.identity_id">
{{ member.display_name }}
</SelectItem>
</SelectContent>
</Select>
</SettingRow>
<SettingRow label="Approval deadline" for="approvals-deadline">
<DurationInput id="approvals-deadline" v-model="draft.approval_deadline" :units="['m', 'h']" />
</SettingRow>
</Section>
<Section title="Escalation path">
<template #action>
<Button type="button" variant="ghost" size="icon" aria-label="Add a step" :disabled="!canAdd" @click="addStep">
<Plus />
</Button>
</template>
<ol class="flex flex-col gap-2">
<li v-for="(step, index) in draft.escalation" :key="index" class="flex flex-wrap items-center gap-3">
<span class="w-6 text-label text-fg-muted">{{ index + 1 }}</span>
<Select v-model="step.account">
<SelectTrigger class="w-64" :aria-label="`Person for step ${index + 1}`">
<SelectValue>{{ nameOf(step.account) }}</SelectValue>
</SelectTrigger>
<SelectContent>
<SelectItem v-for="member in choices(step.account)" :key="member.identity_id" :value="member.identity_id">
{{ member.display_name }}
</SelectItem>
</SelectContent>
</Select>
<DurationInput v-model="step.deadline" :units="['m', 'h']" />
<Button
type="button"
variant="ghost"
size="icon"
:aria-label="`Remove step ${index + 1}`"
@click="draft.escalation.splice(index, 1)"
>
<Trash2 />
</Button>
</li>
</ol>
</Section>
<Alert v-if="saveError" variant="destructive" class="mb-4"><AlertDescription>{{ saveError }}</AlertDescription></Alert>
<div class="flex justify-end gap-2">
<Button type="button" variant="ghost" :disabled="busy || !dirty" @click="draft = toDraft(saved!)">Discard</Button>
<Button type="submit" :disabled="busy || !dirty">Save</Button>
</div>
</form>
</div>
</template>
+11 -17
View File
@@ -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<Member[]>([]);
const candidates = ref<Candidate[]>([]);
const error = ref("");
const loading = ref(true);
const busy = ref("");
@@ -57,9 +58,14 @@ const personRole = ref<Role>("viewer");
async function load(): Promise<void> {
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<void> {
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<void>): Promise<void> {
busy.value = key;
try {
+7
View File
@@ -41,6 +41,13 @@ export const ROLE_LABELS: Record<Role, string> = {
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;
+7
View File
@@ -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",