Multiplayer agent harness for work.
import { randomUUID } from "node:crypto";
import { mintSignedPayload } from "../../../auth/signed-token.ts";
import { scopeId as makeScopeId } from "../../../types.ts";
import { adminStatusFromGrants, AdminError } from "../../../admin/admin-service.ts";
import { personKey, samePerson } from "../../../directory/person.ts";
import type { AdminRole } from "../../../admin/admin-grant-store.ts";
import type { DirectoryMember } from "../../../directory/directory-store.ts";
import { computeUsers } from "../../../admin/users.ts";
import { INVITE_EMAIL_NOT_CONFIGURED, renderInviteEmail } from "../../../admin/invite-email.ts";
import { externalMemberActive, validEmail, type ExternalMember } from "../../../identity/external-members.ts";
import { resolveBranding } from "../../../resolution/branding.ts";
import { errMessage } from "../../../util/errors.ts";
import { normalizeInboundExpiresAt } from "../../expiry.ts";
import { detectOnboardingStatus, setOnboardingStatus, type OnboardingStatus } from "../../../onboarding/onboarding.ts";
import { sendJson } from "../../http.ts";
import { audit, authorizeAdmin, isObj, orgScope } from "../shared.ts";
import { type ApiCtx } from "../route.ts";
const EXTERNAL_ORG_ADMIN_PORTAL_ONLY =
"granting or removing org admin for an external user is portal-only — the agent cannot manage who governs the org";
const ALREADY_A_MEMBER =
"that address already belongs to a member of the org and does not need an external invite. To make them an admin, use Make admin on their row in the admin Users page.";
const HOLDS_OWN_GRANT =
"that address holds an org admin grant of its own — revoke it under Admins first, or re-invite with role org_admin";
const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
const FORGET_AFTER_MS = 24 * 60 * 60 * 1000;
export async function listUsers(ctx: ApiCtx): Promise<void> {
const { res, deps } = ctx;
const scope = orgScope(deps);
const actor = await authorizeAdmin(ctx, scope);
if (!actor) return;
audit(deps, { principalId: actor.id, action: "users.read", resource: "users", scopeLabel: scope });
const participants = (await deps.sessions?.listParticipants()) ?? [];
const turns = (await deps.sessions?.attributedTurns()) ?? [];
const grants = (await deps.admin?.listGrants()) ?? [];
const users = computeUsers({ participants, turns, grants });
const now = Date.now();
const externalUsers = ((await deps.identity?.listExternalMembers()) ?? [])
.map((m) => ({ ...m, status: externalMemberActive(m, now) ? ("active" as const) : ("expired" as const) }))
.sort(
(a, b) =>
Number(b.status === "active") - Number(a.status === "active") ||
(a.expiresAt ?? Infinity) - (b.expiresAt ?? Infinity),
);
for (const member of externalUsers.filter((m) => m.kind === "teammate" && m.status === "active")) {
if (!users.some((u) => samePerson(u.principalId, member.email)))
users.push({
principalId: member.email,
sessionCount: 0,
turnCount: 0,
lastSeenAt: null,
admin: adminStatusFromGrants(grants, member.email),
});
}
const signInUrl = signInUrlOf(deps);
const inviteEmail = {
configured: deps.inviteMailer !== undefined,
...(deps.inviteMailer ? {} : { problem: INVITE_EMAIL_NOT_CONFIGURED }),
...(signInUrl ? { signInUrl } : {}),
};
return sendJson(res, 200, {
scopeId: scope,
users,
grants,
externalUsers,
inviteEmail,
access: {
emailDomain: deps.emailAuthDomain ?? null,
slackAllowFrom: deps.slackAllowFrom ?? null,
},
});
}
function signInUrlOf(deps: ApiCtx["deps"]): string | undefined {
return deps.portalUrl ? `${deps.portalUrl.replace(/\/+$/, "")}/auth/login` : undefined;
}
function endOfDayUtc(value: unknown): unknown {
return typeof value === "string" && DATE_ONLY.test(value.trim()) ? `${value.trim()}T23:59:59.999Z` : value;
}
function grantError(res: ApiCtx["res"], error: string, e: unknown): void {
if (e instanceof AdminError) return sendJson(res, e.status, { error, message: e.message });
throw e;
}
async function orgMember(ctx: ApiCtx, email: string, includeSessions: boolean): Promise<boolean> {
const { deps } = ctx;
if (deps.emailAuthDomain && email.endsWith(`@${deps.emailAuthDomain}`)) return true;
if ((deps.emailAuthPrincipals ?? []).some((principal) => samePerson(principal, email))) return true;
if (await deps.directory?.get(email)) return true;
if (!includeSessions) return false;
const participants = (await deps.sessions?.listParticipants()) ?? [];
return participants.some((participant) => samePerson(participant.principalId, email));
}
export async function inviteExternalUser(ctx: ApiCtx): Promise<void> {
return inviteUser(ctx, false);
}
export async function inviteTeammate(ctx: ApiCtx): Promise<void> {
return inviteUser(ctx, true);
}
async function inviteUser(ctx: ApiCtx, teammate: boolean): Promise<void> {
const { res, deps, body } = ctx;
const scope = orgScope(deps);
const actor = await authorizeAdmin(ctx, scope);
if (!actor) return;
if (!deps.identity) return sendJson(res, 404, { error: "not_found" });
if (teammate && ctx.capability)
return sendJson(res, 403, { error: "forbidden", message: "Teammate invitations must be made in Admin." });
const bad = (message: string) => sendJson(res, 400, { error: "bad_request", message });
const b = isObj(body) ? body : {};
const email = String(b.email ?? "")
.trim()
.toLowerCase();
if (!validEmail(email)) return bad("a valid email address is required");
const role = b.role ?? "member";
if (role !== "member" && role !== "org_admin") return bad("role must be member or org_admin");
const expiry = normalizeInboundExpiresAt(endOfDayUtc(b.expiresAt));
if (!expiry.ok) return bad(expiry.message);
if (teammate && (!deps.portalUrl || !deps.portalIdentitySecret || !deps.replayDedupe?.durable))
return sendJson(res, 503, {
error: "not_configured",
message: "Invitation sign-in requires a portal and durable token storage.",
});
const now = Date.now();
if ((!teammate && expiry.value === undefined) || (expiry.value !== undefined && expiry.value <= now))
return bad("expiresAt is required and must be in the future");
await deps.identity.refresh(true);
if (teammate && deps.identity.deactivationSource(email) === "manual")
return sendJson(res, 409, {
error: "conflict",
message: "This account is manually deactivated. Reactivate it before inviting them.",
});
const existing = deps.identity.externalMember(email);
if (!teammate && existing?.kind === "teammate") return bad("Manage this teammate in Users.");
const holdsGrant = adminStatusFromGrants(await deps.admin!.listGrants(), email).isAdmin;
const ownsGrant = existing?.role === "org_admin";
if (!teammate && ((!existing && holdsGrant) || (await orgMember(ctx, email, !existing))))
return sendJson(res, 409, { error: "conflict", message: ALREADY_A_MEMBER });
if (ctx.capability && (role === "org_admin" || ownsGrant || holdsGrant)) {
return sendJson(res, 403, { error: "forbidden", message: EXTERNAL_ORG_ADMIN_PORTAL_ONLY });
}
if (!teammate && role === "member" && holdsGrant && !ownsGrant)
return sendJson(res, 409, { error: "conflict", message: HOLDS_OWN_GRANT });
let grantChange: "grant.create" | "grant.revoke" | null = null;
if (role === "org_admin" && !holdsGrant) grantChange = "grant.create";
else if (!teammate && role === "member" && holdsGrant) grantChange = "grant.revoke";
try {
if (grantChange === "grant.create")
await deps.admin!.createGrant(actor, { principalId: email, role: "org_admin", scopeId: scope });
else if (grantChange === "grant.revoke") await deps.admin!.revokeGrant(actor, email, scope, "org_admin");
} catch (e) {
return grantError(res, "grant_failed", e);
}
if (grantChange)
audit(deps, { principalId: actor.id, action: grantChange, resource: `${email}/org_admin`, scopeLabel: scope });
const created = existing === undefined;
const readmitted = existing !== undefined && !externalMemberActive(existing, now);
const member: ExternalMember = {
email,
role: teammate && holdsGrant ? "org_admin" : role,
expiresAt: expiry.value ?? null,
...(teammate ? { kind: "teammate" as const, inviteId: randomUUID() } : {}),
invitedBy: existing?.invitedBy ?? actor.id,
createdAt: existing?.createdAt ?? now,
updatedAt: now,
};
await deps.identity.putExternalMember(member);
const action = created || readmitted ? "external_user.invite" : "external_user.update";
audit(deps, {
principalId: actor.id,
action: teammate ? "user.invite" : action,
resource: email,
scopeLabel: scope,
});
const signInUrl = teammate
? `${deps.portalUrl!.replace(/\/+$/, "")}/auth/invite#token=${encodeURIComponent(
await mintSignedPayload(
{
purpose: "teammate-invite",
inviteId: member.inviteId,
email,
org: scope,
aud: deps.portalUrl!.replace(/\/+$/, ""),
iat: now,
exp: now + 24 * 60 * 60 * 1000,
jti: randomUUID(),
},
deps.portalIdentitySecret!,
),
)}`
: signInUrlOf(deps);
let emailSent = false;
let emailProblem: string | undefined;
if (teammate || created || readmitted || b.resendInvite === true) {
if (!deps.inviteMailer) emailProblem = INVITE_EMAIL_NOT_CONFIGURED;
else if (!signInUrl)
emailProblem = "no sign-in URL is configured on core (set PUBLIC_WEB_URL) — share the portal address by hand";
else {
const branding = await resolveBranding(deps.config, scope, deps.brandingDefault);
try {
await deps.inviteMailer.send({
to: email,
...renderInviteEmail({
to: email,
brandName: branding.selfLabel ?? "qm",
invitedBy: actor.id,
signInUrl,
expiresAt: member.expiresAt,
magicLink: teammate,
}),
});
emailSent = true;
} catch (e) {
emailProblem = errMessage(e);
}
}
}
return sendJson(res, 200, {
ok: true,
member,
created,
emailSent,
...(emailProblem ? { emailProblem } : {}),
...(!emailSent && signInUrl ? { signInUrl } : {}),
});
}
export async function revokeExternalUser(ctx: ApiCtx): Promise<void> {
const { res, deps, params } = ctx;
const scope = orgScope(deps);
const actor = await authorizeAdmin(ctx, scope);
if (!actor) return;
if (!deps.identity) return sendJson(res, 404, { error: "not_found" });
await deps.identity.refresh(true);
const existing = deps.identity.externalMember(params.email ?? "");
if (!existing) return sendJson(res, 404, { error: "not_found", message: "external user not found" });
const holdsGrant = adminStatusFromGrants(await deps.admin!.listGrants(), existing.email).isAdmin;
const ownsGrant = existing.role === "org_admin";
if (ctx.capability && (existing.kind === "teammate" || ownsGrant || holdsGrant)) {
return sendJson(res, 403, { error: "forbidden", message: EXTERNAL_ORG_ADMIN_PORTAL_ONLY });
}
if (holdsGrant && !ownsGrant) return sendJson(res, 409, { error: "conflict", message: HOLDS_OWN_GRANT });
if (holdsGrant) {
try {
await deps.admin!.revokeGrant(actor, existing.email, scope, "org_admin");
} catch (e) {
return grantError(res, "revoke_failed", e);
}
audit(deps, {
principalId: actor.id,
action: "grant.revoke",
resource: `${existing.email}/org_admin`,
scopeLabel: scope,
});
}
const now = Date.now();
const tombstone: ExternalMember = {
...existing,
role: "member",
expiresAt: Math.min(existing.expiresAt ?? now, now),
updatedAt: now,
};
if (externalMemberActive(existing, now) || existing.role !== "member") {
await deps.identity.putExternalMember(tombstone);
audit(deps, { principalId: actor.id, action: "external_user.revoke", resource: existing.email, scopeLabel: scope });
}
if (existing.kind === "teammate" || now - tombstone.expiresAt! < FORGET_AFTER_MS)
return sendJson(res, 200, { ok: true, removed: false });
await deps.identity.removeExternalMember(existing.email);
audit(deps, { principalId: actor.id, action: "external_user.forget", resource: existing.email, scopeLabel: scope });
return sendJson(res, 200, { ok: true, removed: true });
}
export async function searchDirectory(ctx: ApiCtx): Promise<void> {
const { res, deps, app, url } = ctx;
const actor = await authorizeAdmin(ctx, orgScope(deps));
if (!actor) return;
const q = (url.searchParams.get("q") ?? "").trim();
if (!q || !deps.directory) return sendJson(res, 200, { members: [] });
const r = await app.resolveRecipient(q);
let members: DirectoryMember[] = [];
if (r.kind === "one") members = [r.member];
else if (r.kind === "ambiguous") members = r.candidates;
return sendJson(res, 200, {
members: members.map((m) => ({ principalId: m.principalId, displayName: m.displayName })),
});
}
export async function listKeychainStatus(ctx: ApiCtx): Promise<void> {
const { res, app, deps } = ctx;
const scope = orgScope(deps);
const actor = await authorizeAdmin(ctx, scope);
if (!actor) return;
audit(deps, { principalId: actor.id, action: "keychain.read", resource: "keychain", scopeLabel: scope });
if (!deps.keychain)
return sendJson(res, 200, { scopeId: scope, people: [], credentials: [], grants: [], asks: [], enabled: false });
const principalId = ctx.url.searchParams.get("principal")?.trim();
if (principalId) {
const [credentials, grants] = await Promise.all([
deps.keychain.listByOwner(principalId),
deps.keychain.listGrants({ ownerId: principalId }),
]);
return sendJson(res, 200, { scopeId: scope, credentials, grants, enabled: true });
}
if (ctx.url.searchParams.get("summary") === "1") {
const [credentials, grants] = await Promise.all([deps.keychain.listAllMetadata(), deps.keychain.listGrants({})]);
return sendJson(res, 200, {
users: new Set(credentials.map((credential) => credential.ownerId)).size,
standing: grants.filter(
(grant) =>
grant.mode === "standing" && grant.status === "active" && (!grant.expiresAt || grant.expiresAt > Date.now()),
).length,
});
}
const [credentials, grants, asks, participantIds, adminGrants] = await Promise.all([
deps.keychain.listAllMetadata(),
deps.keychain.listGrants({}),
deps.keychain.listAsks({}),
deps.sessions?.distinctParticipants() ?? Promise.resolve([]),
deps.admin?.listGrants() ?? Promise.resolve([]),
]);
const ids = new Set<string>([
...credentials.map((c) => c.ownerId),
...grants.map((g) => g.ownerId),
...grants.map((g) => g.usedBy).filter((id): id is string => !!id),
...asks.map((a) => a.ownerId),
...asks.map((a) => a.requesterId),
...participantIds,
...adminGrants.map((g) => g.principalId),
]);
const members = await app.directoryMembers();
const namesByKey = new Map(members.map((m) => [personKey(m.principalId), m.displayName]));
const rosterIdByKey = new Map(members.map((m) => [personKey(m.principalId), m.principalId]));
const idByKey = new Map<string, string>();
for (const id of ids) {
const key = personKey(id);
if (!idByKey.has(key)) idByKey.set(key, rosterIdByKey.get(key) ?? id);
}
const people = [...idByKey.values()].sort().map((principalId) => ({
principalId,
displayName: namesByKey.get(personKey(principalId)) ?? null,
credentialCount: credentials.filter((c) => samePerson(c.ownerId, principalId)).length,
activeGrantCount: grants.filter(
(g) =>
samePerson(g.ownerId, principalId) &&
g.status === "active" &&
(g.expiresAt === undefined || g.expiresAt > Date.now()),
).length,
pendingAskCount: asks.filter((a) => samePerson(a.ownerId, principalId) && a.status === "pending").length,
}));
return sendJson(res, 200, { scopeId: scope, people, credentials, grants, asks, enabled: true });
}
async function resolveAdminUser(deps: ApiCtx["deps"], requestedPrincipal: string) {
const member = await deps.directory?.get(requestedPrincipal);
return { member, principalId: member?.principalId ?? personKey(requestedPrincipal) };
}
export async function getUserDetail(ctx: ApiCtx): Promise<void> {
const { res, deps, params } = ctx;
const org = orgScope(deps);
const actor = await authorizeAdmin(ctx, org);
if (!actor) return;
const { member, principalId } = await resolveAdminUser(deps, params.principalId!);
const personal = makeScopeId("personal", principalId);
audit(deps, { principalId: actor.id, action: "user.read", resource: principalId, scopeLabel: org });
const [grants, stats, onboarding] = await Promise.all([
deps.admin?.listGrants() ?? [],
deps.sessions?.scopeConversationCount(personal),
deps.memory ? deps.memory.read(personal).then(detectOnboardingStatus) : null,
]);
const config = deps.config
? {
hasSoul: !!deps.config.getSoul(personal),
soulVersion: deps.config.soulVersion(personal),
securityPosture: await deps.config.getSecurityPostureDurable(personal),
commandPolicy: deps.config.getCommandPolicy(personal),
egress: deps.config.getEgress(personal),
baseModel: deps.config.getBaseModel(personal),
connectors: await deps.config.listConnectorClients(personal),
}
: null;
return sendJson(res, 200, {
principalId,
scopeId: personal,
...(member?.displayName ? { displayName: member.displayName } : {}),
admin: adminStatusFromGrants(grants, principalId),
stats: { sessions: stats ?? 0 },
config,
onboarding,
});
}
export async function startImpersonation(ctx: ApiCtx): Promise<void> {
const { res, app, deps, body } = ctx;
const org = orgScope(deps);
const actor = await authorizeAdmin(ctx, org);
if (!actor) return;
const target = String((body as { target?: string } | undefined)?.target ?? "").trim();
if (!target) return sendJson(res, 400, { error: "bad_request", message: "target principal required" });
if (target === actor.id) return sendJson(res, 400, { error: "bad_request", message: "cannot impersonate yourself" });
const member = await app.directoryMember(target);
audit(deps, { principalId: actor.id, action: "impersonate.start", resource: target, scopeLabel: org });
return sendJson(res, 200, { ok: true, target, displayName: member?.displayName ?? target });
}
export async function stopImpersonation(ctx: ApiCtx): Promise<void> {
const { res, deps, body } = ctx;
const org = orgScope(deps);
const actor = await authorizeAdmin(ctx, org);
if (!actor) return;
const target = String((body as { target?: string } | undefined)?.target ?? "").trim();
audit(deps, { principalId: actor.id, action: "impersonate.stop", resource: target || "-", scopeLabel: org });
return sendJson(res, 200, { ok: true });
}
const ONBOARDING_STATUSES = new Set<OnboardingStatus>(["not_started", "pending", "completed", "dismissed"]);
export async function setUserOnboarding(ctx: ApiCtx): Promise<void> {
const { res, deps, body, params } = ctx;
const actor = await authorizeAdmin(ctx, orgScope(deps));
if (!actor) return;
if (!deps.memory) return sendJson(res, 404, { error: "not_found" });
const { principalId } = await resolveAdminUser(deps, params.principalId!);
const status = (body as { status?: unknown }).status;
if (typeof status !== "string" || !ONBOARDING_STATUSES.has(status as OnboardingStatus)) {
return sendJson(res, 400, {
error: "bad_request",
message: "onboarding requires { status: not_started|pending|completed|dismissed }",
});
}
const personal = makeScopeId("personal", principalId);
const today = new Date().toISOString().slice(0, 10);
await setOnboardingStatus(deps.memory, personal, status as OnboardingStatus, today, actor.id);
audit(deps, {
principalId: actor.id,
action: "user.onboarding.set",
resource: `${principalId}/${status}`,
scopeLabel: personal,
});
return sendJson(res, 200, { ok: true, scopeId: personal, status });
}
export async function resetUserToBrandNew(ctx: ApiCtx): Promise<void> {
const { res, deps, params } = ctx;
const actor = await authorizeAdmin(ctx, orgScope(deps));
if (!actor) return;
if (!deps.memory) return sendJson(res, 404, { error: "not_found" });
const { principalId } = await resolveAdminUser(deps, params.principalId!);
const personal = makeScopeId("personal", principalId);
const today = new Date().toISOString().slice(0, 10);
await setOnboardingStatus(deps.memory, personal, "not_started", today, actor.id);
let deletedSessions = 0;
if (deps.sessions) {
const own = (await deps.sessions.listByParticipant(principalId)).filter((s) => s.scopeId === personal);
for (const s of own) {
await deps.sessions.deleteSession(s.id);
deletedSessions++;
}
}
audit(deps, {
principalId: actor.id,
action: "user.reset",
resource: `${principalId}/sessions=${deletedSessions}`,
scopeLabel: personal,
});
return sendJson(res, 200, { ok: true, scopeId: personal, deletedSessions });
}
export async function createAdminGrant(ctx: ApiCtx): Promise<void> {
const { res, deps, body } = ctx;
const actor = await authorizeAdmin(ctx, orgScope(deps));
if (!actor) return;
const b = body as { principalId?: string; role?: string; scopeId?: string };
try {
const grant = await deps.admin!.createGrant(actor, {
principalId: String(b.principalId ?? ""),
role: b.role as AdminRole,
scopeId: String(b.scopeId ?? ""),
});
audit(deps, {
principalId: actor.id,
action: "grant.create",
resource: `${grant.principalId}/${grant.role}`,
scopeLabel: grant.scopeId,
});
return sendJson(res, 200, { ok: true, grant });
} catch (e) {
if (e instanceof AdminError) return sendJson(res, e.status, { error: "grant_failed", message: e.message });
throw e;
}
}
export async function revokeAdminGrant(ctx: ApiCtx): Promise<void> {
const { res, deps, url, params } = ctx;
const actor = await authorizeAdmin(ctx, orgScope(deps));
if (!actor) return;
const principalId = params.principalId!;
const scope = url.searchParams.get("scope") ?? "";
const role = url.searchParams.get("role") ?? "";
if (!principalId || !scope || role !== "org_admin") {
return sendJson(res, 400, {
error: "bad_request",
message: "principalId (path), and scope + role=org_admin (query) required",
});
}
try {
await deps.admin!.revokeGrant(actor, principalId, scope, role);
audit(deps, {
principalId: actor.id,
action: "grant.revoke",
resource: `${principalId}/${role}`,
scopeLabel: scope,
});
return sendJson(res, 200, { ok: true });
} catch (e) {
if (e instanceof AdminError) return sendJson(res, e.status, { error: "revoke_failed", message: e.message });
throw e;
}
}