@k2b/cloud 0.45.0 → 0.47.0

package/src/runtime/resolve-connections.ts

@@ -0,0 +1,91 @@
+import { readFileSync } from "node:fs";
+import { envSource } from "../config/define-env";
+import { env } from "../config/env";
+import type { ConnectionSource, PlatformConnections, PlatformConnectionValues } from "./connections";
+
+type EnvKey = keyof typeof env.$specs;
+const explicitlySet = (key: EnvKey): boolean => ["env", "alias", "file"].includes(envSource(env, key));
+
+/** URL diagnostics deliberately omit both the input and underlying parser errors. */
+const url = (key: string, value: string | undefined, bareHost = false): string => {
+  if (!value) throw new Error(`${key} is required for platform start`);
+  try {
+    const parsed = new URL(bareHost && !value.includes("://") ? `nats://${value}` : value);
+    if (bareHost && !parsed.hostname) throw new Error();
+  } catch {
+    throw new Error(`${key} must be a valid URL${bareHost ? " or host:port" : ""}`);
+  }
+  return value;
+};
+const contents = (key: "NATS_CREDS_FILE" | "NATS_TLS_CA_FILE"): string | undefined => {
+  const path = env[key];
+  if (!path) return undefined;
+  try {
+    const value = readFileSync(path, "utf8");
+    if (!value.trim()) throw new Error();
+    return value;
+  } catch {
+    throw new Error(`${key} must name a readable, non-empty file`);
+  }
+};
+
+/**
+ * Explicit environment values always win, including aliases, files and false.
+ * The Core bootstrap client supplies `core` in key mode; required values then
+ * never fall through to environment defaults. Optional values may use defaults.
+ */
+export const resolveConnections = ({ appId, core }: { appId: string; core?: PlatformConnectionValues }): PlatformConnections => {
+  const source = (key: EnvKey): ConnectionSource => (!core || explicitlySet(key) ? "env" : "core");
+  const choose = <T>(key: EnvKey, fromEnv: () => T, fromCore: T): T => (!core || explicitlySet(key) ? fromEnv() : fromCore);
+  // Keep value reads lazy: an absent env value must not evaluate its default in key mode.
+  const database = url(
+    "DATABASE_URL",
+    choose("DATABASE_URL", () => env.DATABASE_URL, core?.database.url),
+  );
+  const valkey = url(
+    "REDIS_URL",
+    choose("REDIS_URL", () => env.REDIS_URL, core?.valkey.url),
+  );
+  const servers = choose("NATS_SERVERS", () => env.NATS_SERVERS, core?.nats.servers) ?? [];
+  for (const server of servers) url("NATS_SERVERS", server, true);
+  const namespace = choose("SYNC_NAMESPACE", () => env.SYNC_NAMESPACE, core?.nats.namespace) ?? "";
+  const replicas = choose("SYNC_REPLICAS", () => env.SYNC_REPLICAS, core?.nats.replicas) ?? env.SYNC_REPLICAS;
+  const ignoreClusterUpdates =
+    choose("NATS_IGNORE_CLUSTER_UPDATES", () => env.NATS_IGNORE_CLUSTER_UPDATES, core?.nats.ignoreClusterUpdates) ??
+    env.NATS_IGNORE_CLUSTER_UPDATES;
+  const creds = choose("NATS_CREDS_FILE", () => contents("NATS_CREDS_FILE"), core?.nats.creds);
+  const ca = choose("NATS_TLS_CA_FILE", () => contents("NATS_TLS_CA_FILE"), core?.nats.ca);
+  const secret = choose("APP_SECRET", () => env.APP_SECRET, core?.appSecret.current) ?? "";
+  const rotation = core && !explicitlySet("APP_SECRET") ? core.appSecret : undefined;
+  if (core) {
+    if (servers.length === 0) throw new Error("NATS_SERVERS is required for platform start");
+    if (!namespace.trim()) throw new Error("SYNC_NAMESPACE is required for platform start");
+    if (!secret.trim()) throw new Error("APP_SECRET is required for platform start");
+  }
+  if (![1, 3, 5].includes(replicas)) throw new Error("SYNC_REPLICAS must be 1, 3, or 5");
+  if (typeof ignoreClusterUpdates !== "boolean") throw new Error("NATS_IGNORE_CLUSTER_UPDATES must be a boolean");
+  return {
+    appId,
+    database: { url: database },
+    valkey: { url: valkey },
+    nats: { servers: [...servers], namespace, replicas, ignoreClusterUpdates, creds, ca },
+    appSecret: { current: secret, previous: rotation?.previous, next: rotation?.next },
+    sources: {
+      database: { url: source("DATABASE_URL") },
+      valkey: { url: source("REDIS_URL") },
+      nats: {
+        servers: source("NATS_SERVERS"),
+        namespace: source("SYNC_NAMESPACE"),
+        replicas: source("SYNC_REPLICAS"),
+        ignoreClusterUpdates: source("NATS_IGNORE_CLUSTER_UPDATES"),
+        creds: source("NATS_CREDS_FILE"),
+        ca: source("NATS_TLS_CA_FILE"),
+      },
+      appSecret: {
+        current: source("APP_SECRET"),
+        ...(rotation?.previous ? { previous: "core" as const } : {}),
+        ...(rotation?.next ? { next: "core" as const } : {}),
+      },
+    },
+  };
+};

package/src/server/client-ip.ts

@@ -1,7 +1,7 @@
 import { isIP } from "node:net";
 import type { Context } from "hono";
 
-// The gateway (packages/gateway/src/client-address.ts) resolves this address using GATEWAY_TRUSTED_PROXIES.
+// The gateway (packages/gateway/src/client-address.ts) resolves this address using the gateway.trusted_proxies setting.
 export const clientIp = (c: Context): string =>
   c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ?? c.req.header("x-real-ip") ?? "unknown";
 

package/src/services/accounts/app.ts

@@ -14,6 +14,7 @@ import type {
   UserProfile,
   UserProvider,
 } from "../../contracts/shared";
+import type { ServiceAccountRequestActor } from "../../server/middleware/auth";
 import {
   err,
   fail,
@@ -41,6 +42,7 @@ import type { AvatarChange, AvatarState } from "./avatar";
 import { listDuplicateEmails } from "./duplicate-emails";
 import * as entities from "./entities";
 import * as groups from "./groups";
+import { mutateMachineGroupMember } from "./machine-group-management";
 import type { AccountsNotificationSender } from "./notification-sender";
 import { PosixError } from "./posix";
 import { accountRequestsEnabled } from "./request-policy";
@@ -1018,13 +1020,15 @@ export const accountsAppService = {
         return paginateItems(filtered, config.pagination);
       },
       add: async (config: {
-        actor: AccountsActor;
+        actor: AccountsActor | ServiceAccountRequestActor;
+        requestId?: string;
         id: string;
         provider?: UserProvider;
         userId?: string;
         groupId?: string;
         serviceAccountId?: string;
       }) => {
+        if ("kind" in config.actor) return mutateMachineGroupMember({ ...config, actor: config.actor, operation: "add" });
         const group = await groups.get({ id: config.id });
         if (!group) {
           const result = fail(err.notFound("Group not found"));
@@ -1055,13 +1059,15 @@ export const accountsAppService = {
         });
       },
       remove: async (config: {
-        actor: AccountsActor;
+        actor: AccountsActor | ServiceAccountRequestActor;
+        requestId?: string;
         id: string;
         provider?: UserProvider;
         userId?: string;
         groupId?: string;
         serviceAccountId?: string;
       }) => {
+        if ("kind" in config.actor) return mutateMachineGroupMember({ ...config, actor: config.actor, operation: "remove" });
         const group = await groups.get({ id: config.id });
         if (!group) {
           const result = fail(err.notFound("Group not found"));
@@ -1110,7 +1116,14 @@ export const accountsAppService = {
         });
         return paginateItems(filtered, config.pagination);
       },
-      add: async (config: { actor: AccountsActor; id: string; provider?: UserProvider; userId?: string; groupId?: string }) => {
+      add: async (config: {
+        actor: AccountsActor;
+        id: string;
+        provider?: UserProvider;
+        userId?: string;
+        groupId?: string;
+        serviceAccountId?: string;
+      }) => {
         const group = await groups.get({ id: config.id });
         if (!group) {
           const result = fail(err.notFound("Group not found"));
@@ -1133,17 +1146,25 @@ export const accountsAppService = {
             provider: config.provider,
             user: config.userId,
             group: config.groupId,
+            serviceAccount: config.serviceAccountId,
           }),
         );
         return recordCompletedMutation({
           action: "accounts.group.manager.add",
           actor: auditActor(config.actor),
           target: groupTarget(group),
-          metadata: { userId: config.userId ?? null, groupId: config.groupId ?? null },
+          metadata: { userId: config.userId ?? null, groupId: config.groupId ?? null, serviceAccountId: config.serviceAccountId ?? null },
           result,
         });
       },
-      remove: async (config: { actor: AccountsActor; id: string; provider?: UserProvider; userId?: string; groupId?: string }) => {
+      remove: async (config: {
+        actor: AccountsActor;
+        id: string;
+        provider?: UserProvider;
+        userId?: string;
+        groupId?: string;
+        serviceAccountId?: string;
+      }) => {
         const group = await groups.get({ id: config.id });
         if (!group) {
           const result = fail(err.notFound("Group not found"));
@@ -1166,13 +1187,14 @@ export const accountsAppService = {
             provider: config.provider,
             user: config.userId,
             group: config.groupId,
+            serviceAccount: config.serviceAccountId,
           }),
         );
         return recordCompletedMutation({
           action: "accounts.group.manager.remove",
           actor: auditActor(config.actor),
           target: groupTarget(group),
-          metadata: { userId: config.userId ?? null, groupId: config.groupId ?? null },
+          metadata: { userId: config.userId ?? null, groupId: config.groupId ?? null, serviceAccountId: config.serviceAccountId ?? null },
           result,
         });
       },

package/src/services/accounts/entities.ts

@@ -484,8 +484,8 @@ export const list = async (
             AND ug.group_id = ANY(${toPgUuidArray(params.userMemberOfGroupIds ?? [])}::uuid[])
         ))`;
 
-  // Machine recipients have local membership, but no directory management/parent relation.
-  const otherRelation = Boolean(params.managerOfGroupId || params.parentGroupId || params.managedByUserId);
+  // Machine management is direct only; membership never implies management.
+  const otherRelation = Boolean(params.parentGroupId || params.managedByUserId);
   const machineRelation = params.memberOfGroupId
     ? sql`sa.kind IN ('standalone', 'agent') AND EXISTS (
         SELECT 1 FROM auth.groups target
@@ -497,11 +497,18 @@ export const list = async (
                   WHERE sg.service_account_id = sa.id AND sg.group_id = target.id)`
           }
       )`
-    : sql`TRUE`;
+    : params.managerOfGroupId
+      ? sql`sa.kind IN ('standalone', 'agent') AND EXISTS (
+        SELECT 1 FROM auth.group_manager_service_accounts gm JOIN auth.groups g ON g.id = gm.group_id
+        WHERE gm.service_account_id = sa.id AND gm.group_id = ${params.managerOfGroupId}::uuid AND g.provider = 'local'
+      )`
+      : sql`TRUE`;
   const machineDirect = params.memberOfGroupId
     ? sql`EXISTS (SELECT 1 FROM auth.service_account_groups sg
         WHERE sg.service_account_id = sa.id AND sg.group_id = ${params.memberOfGroupId}::uuid)`
-    : sql`NULL::boolean`;
+    : params.managerOfGroupId
+      ? sql`TRUE`
+      : sql`NULL::boolean`;
   const where = sql`
     ${visibilityCondition}
     AND ${kindsCondition}

package/src/services/accounts/groups.ts

@@ -264,9 +264,12 @@ export const addManager = async (params: {
   provider?: UserProvider;
   user?: string;
   group?: string;
+  serviceAccount?: string;
 }): Promise<MutationResult<void>> => {
-  const provider = params.provider ?? (await getGroup(params.id))?.provider;
-  if (provider === "local") return localGroups.addManager({ id: params.id, user: params.user, group: params.group });
+  const provider = (await getGroup(params.id))?.provider;
+  if (provider === "local")
+    return localGroups.addManager({ id: params.id, user: params.user, group: params.group, serviceAccount: params.serviceAccount });
+  if (params.serviceAccount) return { ok: false, error: "Machine management requires a local group", status: 400 };
   const serviceSession = await getServiceIpaSession();
   if (!serviceSession.ok) return serviceSession;
   return providers.ipa.groups.addManager({
@@ -282,9 +285,12 @@ export const removeManager = async (params: {
   provider?: UserProvider;
   user?: string;
   group?: string;
+  serviceAccount?: string;
 }): Promise<MutationResult<void>> => {
-  const provider = params.provider ?? (await getGroup(params.id))?.provider;
-  if (provider === "local") return localGroups.removeManager({ id: params.id, user: params.user, group: params.group });
+  const provider = (await getGroup(params.id))?.provider;
+  if (provider === "local")
+    return localGroups.removeManager({ id: params.id, user: params.user, group: params.group, serviceAccount: params.serviceAccount });
+  if (params.serviceAccount) return { ok: false, error: "Machine management requires a local group", status: 400 };
   const serviceSession = await getServiceIpaSession();
   if (!serviceSession.ok) return serviceSession;
   return providers.ipa.groups.removeManager({

package/src/services/accounts/local-groups.ts

@@ -1,4 +1,4 @@
-import { sql } from "bun";
+import { sql, type TransactionSQL } from "bun";
 import type { BaseGroup, GroupMember, MutationResult, UserProvider } from "../../contracts/shared";
 import { escapeLikePattern, isUniqueViolation } from "../postgres";
 import { buildBaseGroup, personalOwnerJoin } from "./base-group";
@@ -23,8 +23,8 @@ const toBaseGroup = (row: LocalGroupRow): BaseGroup => ({
   personalOwner: null,
 });
 
-const getLocalGroupById = async (id: string): Promise<LocalGroupRow | null> => {
-  const [row] = await sql<DbRow[]>`
+const getLocalGroupById = async (id: string, db: typeof sql | TransactionSQL = sql): Promise<LocalGroupRow | null> => {
+  const [row] = await db<DbRow[]>`
     SELECT id, provider, name, description, gid_number
     FROM auth.groups
     WHERE id = ${id}::uuid AND provider = 'local'
@@ -39,20 +39,23 @@ const getLocalGroupById = async (id: string): Promise<LocalGroupRow | null> => {
   };
 };
 
-const getUserProvider = async (userId: string): Promise<UserProvider | null> => {
-  const [row] = await sql<DbRow[]>`SELECT provider FROM auth.users WHERE id = ${userId}`;
+const getUserProvider = async (userId: string, db: typeof sql | TransactionSQL = sql): Promise<UserProvider | null> => {
+  const [row] = await db<DbRow[]>`SELECT provider FROM auth.users WHERE id = ${userId}`;
   return (row?.provider as UserProvider | undefined) ?? null;
 };
 
-const ensureLocalGroupTreeMember = async (groupId: string): Promise<boolean> => {
-  const [row] = await sql<DbRow[]>`SELECT 1 FROM auth.groups WHERE id = ${groupId} AND provider = 'local'`;
+const ensureLocalGroupTreeMember = async (groupId: string, db: typeof sql | TransactionSQL = sql): Promise<boolean> => {
+  const [row] = await db<DbRow[]>`SELECT 1 FROM auth.groups WHERE id = ${groupId} AND provider = 'local'`;
   return Boolean(row);
 };
 
-const wouldCreateLocalGroupCycle = async (params: { parentGroupId: string; childGroupId: string }): Promise<boolean> => {
+const wouldCreateLocalGroupCycle = async (
+  params: { parentGroupId: string; childGroupId: string },
+  db: typeof sql | TransactionSQL = sql,
+): Promise<boolean> => {
   if (params.parentGroupId === params.childGroupId) return true;
 
-  const [row] = await sql<DbRow[]>`
+  const [row] = await db<DbRow[]>`
     WITH RECURSIVE descendants AS (
       SELECT gg.child_group_id
       FROM auth.group_groups_v2 gg
@@ -272,7 +275,11 @@ export const getMembers = async (params: { id: string; type?: GroupMember["type"
   return members;
 };
 
-export const getManagers = async (params: { id: string; type?: "user" | "group"; recursive?: boolean }): Promise<GroupMember[]> => {
+export const getManagers = async (params: {
+  id: string;
+  type?: "user" | "group" | "service_account";
+  recursive?: boolean;
+}): Promise<GroupMember[]> => {
   const group = await getLocalGroupById(params.id);
   if (!group) return [];
 
@@ -342,6 +349,16 @@ export const getManagers = async (params: { id: string; type?: "user" | "group";
     }
   }
 
+  if (!params.type || params.type === "service_account") {
+    const rows = await sql<{ id: string; name: string; kind: "standalone" | "agent" }[]>`
+      SELECT sa.id, sa.name, sa.kind FROM auth.group_manager_service_accounts gm
+      JOIN auth.service_accounts sa ON sa.id = gm.service_account_id
+      WHERE gm.group_id = ${group.id}::uuid AND sa.kind IN ('standalone', 'agent')
+      ORDER BY sa.name, sa.id`;
+    managers.push(
+      ...rows.map((row) => ({ type: "service_account" as const, id: row.id, displayName: row.name, serviceAccountKind: row.kind })),
+    );
+  }
   return managers;
 };
 
@@ -416,25 +433,28 @@ export const getManagedGroups = async (params: { id: string; recursive?: boolean
   return rows.map((row) => row.group_id as string);
 };
 
-export const addMember = async (params: {
-  id: string;
-  user?: string;
-  group?: string;
-  serviceAccount?: string;
-}): Promise<MutationResult<void>> => {
-  const group = await getLocalGroupById(params.id);
+export const addMember = async (
+  params: {
+    id: string;
+    user?: string;
+    group?: string;
+    serviceAccount?: string;
+  },
+  db: typeof sql | TransactionSQL = sql,
+): Promise<MutationResult<void>> => {
+  const group = await getLocalGroupById(params.id, db);
   if (!group) return { ok: false, error: "Group not found", status: 404 };
   const [personal] = await sql`SELECT 1 FROM auth.personal_groups
     WHERE group_id = ${group.id}::uuid OR group_id = ${params.group ?? null}::uuid`;
   if (personal) return { ok: false, error: "Personal Linux groups cannot be used in group relationships", status: 409 };
 
   if (params.serviceAccount) {
-    const [account] = await sql<{ id: string }[]>`
+    const [account] = await db<{ id: string }[]>`
       SELECT id FROM auth.service_accounts
       WHERE id = ${params.serviceAccount}::uuid AND status = 'active' AND kind IN ('standalone', 'agent')
     `;
     if (!account) return { ok: false, error: "An active standalone or agent account is required", status: 400 };
-    const inserted = await sql`
+    const inserted = await db`
       INSERT INTO auth.service_account_groups (service_account_id, group_id)
       VALUES (${account.id}::uuid, ${group.id}::uuid) ON CONFLICT DO NOTHING
     `;
@@ -443,9 +463,9 @@ export const addMember = async (params: {
   }
 
   if (params.user) {
-    const provider = await getUserProvider(params.user);
+    const provider = await getUserProvider(params.user, db);
     if (!provider) return { ok: false, error: "User not found", status: 404 };
-    const [existing] = await sql<DbRow[]>`
+    const [existing] = await db<DbRow[]>`
       SELECT 1
       FROM auth.user_groups_v2
       WHERE user_id = ${params.user}::uuid
@@ -453,14 +473,14 @@ export const addMember = async (params: {
       LIMIT 1
     `;
     if (existing) return { ok: false, error: "User is already a direct member of this group", status: 409 };
-    await sql`INSERT INTO auth.user_groups_v2 (user_id, group_id) VALUES (${params.user}, ${group.id}) ON CONFLICT DO NOTHING`;
+    await db`INSERT INTO auth.user_groups_v2 (user_id, group_id) VALUES (${params.user}, ${group.id}) ON CONFLICT DO NOTHING`;
     return { ok: true, data: undefined };
   }
 
   if (params.group) {
-    const isLocal = await ensureLocalGroupTreeMember(params.group);
+    const isLocal = await ensureLocalGroupTreeMember(params.group, db);
     if (!isLocal) return { ok: false, error: "Only local groups can be nested into local groups", status: 400 };
-    const [existing] = await sql<DbRow[]>`
+    const [existing] = await db<DbRow[]>`
       SELECT 1
       FROM auth.group_groups_v2
       WHERE parent_group_id = ${group.id}::uuid
@@ -468,51 +488,69 @@ export const addMember = async (params: {
       LIMIT 1
     `;
     if (existing) return { ok: false, error: "Group is already a direct member of this group", status: 409 };
-    if (await wouldCreateLocalGroupCycle({ parentGroupId: group.id, childGroupId: params.group })) {
+    if (await wouldCreateLocalGroupCycle({ parentGroupId: group.id, childGroupId: params.group }, db)) {
       return { ok: false, error: "Local group nesting cannot create cycles", status: 400 };
     }
-    await sql`INSERT INTO auth.group_groups_v2 (parent_group_id, child_group_id) VALUES (${group.id}, ${params.group}) ON CONFLICT DO NOTHING`;
+    await db`INSERT INTO auth.group_groups_v2 (parent_group_id, child_group_id) VALUES (${group.id}, ${params.group}) ON CONFLICT DO NOTHING`;
     return { ok: true, data: undefined };
   }
 
   return { ok: false, error: "Missing member", status: 400 };
 };
 
-export const removeMember = async (params: {
-  id: string;
-  user?: string;
-  group?: string;
-  serviceAccount?: string;
-}): Promise<MutationResult<void>> => {
-  const group = await getLocalGroupById(params.id);
+export const removeMember = async (
+  params: {
+    id: string;
+    user?: string;
+    group?: string;
+    serviceAccount?: string;
+  },
+  db: typeof sql | TransactionSQL = sql,
+): Promise<MutationResult<void>> => {
+  const group = await getLocalGroupById(params.id, db);
   if (!group) return { ok: false, error: "Group not found", status: 404 };
 
   if (params.serviceAccount) {
-    await sql`DELETE FROM auth.service_account_groups
+    await db`DELETE FROM auth.service_account_groups
       WHERE service_account_id = ${params.serviceAccount}::uuid AND group_id = ${group.id}::uuid`;
     return { ok: true, data: undefined };
   }
 
   if (params.user) {
-    await sql`DELETE FROM auth.user_groups_v2 WHERE user_id = ${params.user}::uuid AND group_id = ${group.id}::uuid`;
+    await db`DELETE FROM auth.user_groups_v2 WHERE user_id = ${params.user}::uuid AND group_id = ${group.id}::uuid`;
     return { ok: true, data: undefined };
   }
 
   if (params.group) {
-    await sql`DELETE FROM auth.group_groups_v2 WHERE parent_group_id = ${group.id}::uuid AND child_group_id = ${params.group}::uuid`;
+    await db`DELETE FROM auth.group_groups_v2 WHERE parent_group_id = ${group.id}::uuid AND child_group_id = ${params.group}::uuid`;
     return { ok: true, data: undefined };
   }
 
   return { ok: false, error: "Missing member", status: 400 };
 };
 
-export const addManager = async (params: { id: string; user?: string; group?: string }): Promise<MutationResult<void>> => {
+export const addManager = async (params: {
+  id: string;
+  user?: string;
+  group?: string;
+  serviceAccount?: string;
+}): Promise<MutationResult<void>> => {
   const group = await getLocalGroupById(params.id);
   if (!group) return { ok: false, error: "Group not found", status: 404 };
   const [personal] = await sql`SELECT 1 FROM auth.personal_groups
     WHERE group_id = ${group.id}::uuid OR group_id = ${params.group ?? null}::uuid`;
   if (personal) return { ok: false, error: "Personal Linux groups cannot be used in group relationships", status: 409 };
 
+  if (params.serviceAccount) {
+    const [account] = await sql`SELECT id FROM auth.service_accounts
+      WHERE id = ${params.serviceAccount}::uuid AND status = 'active' AND kind IN ('standalone', 'agent')`;
+    if (!account) return { ok: false, error: "An active standalone or agent account is required", status: 400 };
+    const inserted = await sql`INSERT INTO auth.group_manager_service_accounts(group_id, service_account_id)
+      VALUES (${group.id}::uuid, ${params.serviceAccount}::uuid) ON CONFLICT DO NOTHING`;
+    if (inserted.count === 0) return { ok: false, error: "Service account already manages this group", status: 409 };
+    return { ok: true, data: undefined };
+  }
+
   if (params.user) {
     const provider = await getUserProvider(params.user);
     if (!provider) return { ok: false, error: "User not found", status: 404 };
@@ -546,10 +584,21 @@ export const addManager = async (params: { id: string; user?: string; group?: st
   return { ok: false, error: "Missing manager", status: 400 };
 };
 
-export const removeManager = async (params: { id: string; user?: string; group?: string }): Promise<MutationResult<void>> => {
+export const removeManager = async (params: {
+  id: string;
+  user?: string;
+  group?: string;
+  serviceAccount?: string;
+}): Promise<MutationResult<void>> => {
   const group = await getLocalGroupById(params.id);
   if (!group) return { ok: false, error: "Group not found", status: 404 };
 
+  if (params.serviceAccount) {
+    await sql`DELETE FROM auth.group_manager_service_accounts
+      WHERE group_id = ${group.id}::uuid AND service_account_id = ${params.serviceAccount}::uuid`;
+    return { ok: true, data: undefined };
+  }
+
   if (params.user) {
     await sql`DELETE FROM auth.group_manager_users_v2 WHERE group_id = ${group.id}::uuid AND user_id = ${params.user}::uuid`;
     return { ok: true, data: undefined };

package/src/services/accounts/machine-group-management.ts

@@ -0,0 +1,94 @@
+import { sql } from "bun";
+import type { ServiceAccountRequestActor } from "../../server/middleware/auth";
+import { err, fail, ok, type Result } from "../../server/services";
+import { audit } from "../audit";
+import * as localGroups from "./local-groups";
+
+/** Runs the existing local membership operation while its direct management grant is locked. */
+export async function mutateMachineGroupMember(params: {
+  actor: ServiceAccountRequestActor;
+  id: string;
+  userId?: string;
+  groupId?: string;
+  serviceAccountId?: string;
+  operation: "add" | "remove";
+  requestId?: string;
+}): Promise<Result<void>> {
+  const { actor } = params;
+  const action = `accounts.group.member.${params.operation}`;
+  const target = { type: "group", id: params.id };
+  const metadata = {
+    actorServiceAccountId: actor.serviceAccount.id,
+    credentialId: actor.credentialId ?? null,
+    oauthClientId: actor.oauthClientId ?? null,
+    userId: params.userId ?? null,
+    groupId: params.groupId ?? null,
+    serviceAccountId: params.serviceAccountId ?? null,
+  };
+  const unexpired = (expiration: string | Date | null | undefined) =>
+    expiration == null || (typeof expiration === "string" ? Date.parse(expiration) : expiration.getTime()) > Date.now();
+  const denied = () => fail(err.forbidden("A current management grant for this group and write scope are required"));
+  if (
+    actor.delegatedUser ||
+    !["standalone", "agent"].includes(actor.serviceAccount.kind) ||
+    !actor.scopes.some((scope) => scope === "write" || scope === "admin") ||
+    !unexpired(actor.credentialExpiresAt) ||
+    (!actor.credentialId && (!actor.oauthClientId || !actor.credentialExpiresAt))
+  )
+    return audit.recordResult({ action, target, metadata, requestId: params.requestId, result: denied() });
+
+  return sql.begin(async (db) => {
+    // Account -> credential -> group -> grant matches the group deletion cascade.
+    const [account] = await db`SELECT id FROM auth.service_accounts
+      WHERE id = ${actor.serviceAccount.id}::uuid AND status = 'active' AND kind IN ('standalone','agent') FOR SHARE`;
+    let allowed = Boolean(account);
+    let storedExpiration: Date | null = null;
+    if (allowed && actor.credentialId) {
+      const [credential] = await db<{ expires_at: Date | null }[]>`SELECT expires_at FROM auth.service_account_credentials
+        WHERE id = ${actor.credentialId}::uuid AND service_account_id = ${actor.serviceAccount.id}::uuid
+          AND status = 'active' AND (expires_at IS NULL OR expires_at > clock_timestamp())
+          AND scopes && ARRAY['write','admin']::text[] FOR SHARE`;
+      allowed = Boolean(credential);
+      storedExpiration = credential?.expires_at ?? null;
+    } else if (allowed) {
+      const [client] = await db`SELECT id FROM oauth.clients WHERE client_id=${actor.oauthClientId ?? null} FOR SHARE`;
+      allowed = Boolean(client);
+    }
+    const [group] = allowed ? await db`SELECT id FROM auth.groups WHERE id=${params.id}::uuid AND provider='local' FOR SHARE` : [];
+    const [grant] = group
+      ? await db`SELECT group_id FROM auth.group_manager_service_accounts
+        WHERE group_id=${params.id}::uuid AND service_account_id=${actor.serviceAccount.id}::uuid FOR SHARE`
+      : [];
+    let result: Result<void> = denied();
+    // The authorization locks define admission; time must be current after any lock wait.
+    if (grant && unexpired(actor.credentialExpiresAt) && unexpired(storedExpiration)) {
+      if ([params.userId, params.groupId, params.serviceAccountId].filter(Boolean).length !== 1) {
+        result = fail(err.badInput("Choose exactly one member"));
+      } else {
+        const changed = await localGroups[params.operation === "add" ? "addMember" : "removeMember"](
+          {
+            id: params.id,
+            user: params.userId,
+            group: params.groupId,
+            serviceAccount: params.serviceAccountId,
+          },
+          db,
+        );
+        result = changed.ok
+          ? ok()
+          : fail({ code: changed.status === 403 ? "FORBIDDEN" : "GROUP_MUTATION_FAILED", message: changed.error, status: changed.status });
+      }
+    }
+    await audit.record(
+      {
+        action,
+        target,
+        metadata,
+        requestId: params.requestId,
+        outcome: result.ok ? "allowed" : result.error.status === 403 ? "denied" : "failed",
+      },
+      db,
+    );
+    return result;
+  });
+}