Skip to content

⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.

32.6 KB
Raw Blame
import { Elysia, t } from 'elysia';
import {
  GOOGLE_REDIRECT_URI,
  OIDC_REDIRECT_URI,
  getAuthSettings,
  setAuthSettings,
  getEmailSettings,
  resolveEmailConfig,
  setEmailSettings,
  getGoogleSettings,
  setGoogleSettings,
  hasConfiguredGoogle,
  getOidcSettings,
  setOidcSettings,
  getScimSettings,
  setScimSettings,
  rotateScimToken,
  hasConfiguredOidc,
  composeEmail,
  emailLocale,
} from '@repo/auth';
import { hasConfiguredEmailProvider, getStorageSettings } from '@repo/db';
import { hasEmailProvider } from '@repo/mailer';
import { authContext } from '#shared/auth-context';
import { requireGod } from '#shared/access';
import { HttpError, rethrowDuplicate } from '#shared/lib';
import { accessErrors, commonErrors, errors } from '#shared/responses';
import { paginate } from '#shared/pagination';
import { noContent } from '#shared/http';
import { deleteProject } from '#modules/projects/service';
import { SCIM_BASE_URL } from '#modules/scim/resource';
import {
  MappableProjectListResponse,
  ScimGroupMappingsBody,
  ProvisionedGroupResponse,
  ScimSettingsBody,
  ScimSettingsResponse,
  ScimTokenResponse,
} from '#modules/scim/model';
import {
  listMappableProjects,
  listProvisionedGroups,
  setGroupMappings,
} from '#modules/scim/mappings';
import {
  deleteInstanceUser,
  getInstanceProject,
  getInstanceTeam,
  getInstanceUser,
  listInstanceProjects,
  listInstanceTeams,
  listInstanceTeamProjects,
  listInstanceTeamMembers,
  listInstanceUsers,
  setInstanceUserActive,
  verifyInstanceUserEmail,
  type ActiveLock,
} from './service';
import {
  AuthSettingsBody,
  AuthSettingsResponse,
  EmailSettingsBody,
  EmailSettingsResponse,
  EmailDraftBody,
  EmailPreviewResponse,
  EmailTemplatesBody,
  EmailTemplatesResponse,
  EmailTestResponse,
  GoogleSettingsBody,
  GoogleSettingsResponse,
  InstanceProjectDetailResponse,
  InstanceProjectPageResponse,
  InstanceTeamMemberPageResponse,
  InstanceTeamPageResponse,
  InstanceTeamProjectPageResponse,
  InstanceTeamResponse,
  InstanceUserDetailResponse,
  InstanceUserPageResponse,
  OidcSettingsBody,
  OidcSettingsResponse,
  StorageSettingsBody,
  TelegramSettingsBody,
  TelegramSettingsResponse,
  deleteUserQuery,
  listUsersQuery,
  projectParams,
  roleParams,
  scimGroupParams,
  searchPageQuery,
  teamParams,
  userParams,
} from './model';
import { deliverTestEmail } from './email-test';
import {
  getEmailTemplates,
  previewEmail,
  saveEmailTemplates,
  sendTestEmail,
} from './email-templates';
import { getInstanceBotSettings, setInstanceBotSettings } from '#modules/telegram/service';
import {
  setStorageSettings,
  getHotkeySettings,
  setHotkeySettings,
  getEmbedSites,
  setEmbedSites,
  getProjectDefaults,
  setProjectDefaults,
  getAgentSettings,
  setAgentSettings,
  getSharingSettings,
  setSharingSettings,
} from '#modules/settings/service';
import { getUpdateStatus } from '#modules/settings/updates';
import { RoleResponse, createRoleBody, updateRoleBody } from '#modules/roles/model';
import {
  createRole,
  deleteRole,
  getRole,
  getRoleUsage,
  isRoleInUse,
  listRoles,
  updateRole,
} from '#modules/roles/service';
import {
  AgentSettingsSchema,
  EmbedSitesSchema,
  HotkeyCombosSchema,
  ProjectDefaultsSchema,
  SharingSettingsSchema,
  StorageSettingsSchema,
  UpdateStatusSchema,
} from '#modules/settings/model';

// God mode: instance-wide administration, open only to the "god" user (the first
// registered account). It covers how people may register, the mail provider that
// sends authentication email, the OAuth credentials, and the instance's SCIM
// provisioning. Invites are per team (team_invite), managed in the team panel and in the
// project's Members section — there is nothing instance-level to add here.
//
// The settings themselves are owned by @repo/auth, which reads them at sign-up and
// when sending mail; these routes only expose them over HTTP. Secrets are never
// returned — each is replaced by a boolean telling whether a value is stored.

// Whether any single sign-on provider can run right now. Password sign-in may only
// be turned off while one can.
async function hasSsoProvider(): Promise<boolean> {
  return (await hasConfiguredOidc()) || (await hasConfiguredGoogle());
}

async function assertUsableSignInMethod(
  nextProviderUsable: boolean,
  otherProviderUsable: boolean,
): Promise<void> {
  const auth = await getAuthSettings();
  if (!auth.emailPassword && !nextProviderUsable && !otherProviderUsable) {
    throw new HttpError(400, 'Enable password sign-in or another single sign-on provider first');
  }
}

// Deactivating the instance owner is how an instance locks itself out, and an agent's
// account follows its agent; with SCIM the identity provider decides.
function assertActiveSwitchable(lock: ActiveLock | null): void {
  if (lock === 'owner') throw new HttpError(403, 'An instance owner cannot be deactivated');
  if (lock === 'agent') throw new HttpError(403, "An agent's account follows its agent");
  if (lock === 'scim') {
    throw new HttpError(409, 'Accounts are activated and deactivated by the SCIM provider');
  }
}

export const godRoutes = new Elysia({ name: 'god', detail: { tags: ['God'] } })
  .use(authContext)
  // Every route in this plugin is instance administration, so the role check runs
  // once here instead of per route.
  .onBeforeHandle(({ user }) => {
    requireGod(user);
  })

  .get(
    '/god/auth-settings',
    async () => ({
      ...(await getAuthSettings()),
      hasEmailProvider: await hasConfiguredEmailProvider(),
      hasSsoProvider: await hasSsoProvider(),
    }),
    {
      response: { 200: AuthSettingsResponse, ...errors(401, 403) },
      detail: {
        summary: 'Get authentication settings',
        description:
          'Get the instance registration mode, allowed email domains, invite lifetime and email-dependent auth options.',
      },
    },
  )

  .put(
    '/god/auth-settings',
    async ({ body }) => {
      const ready = await hasConfiguredEmailProvider();
      // Verification mail and magic links have no way to reach the user without a
      // provider, so they cannot be turned on before one is configured.
      if (!ready && (body.requireEmailVerification || body.magicLink)) {
        throw new HttpError(400, 'Configure an email provider first');
      }
      const sso = await hasSsoProvider();
      // Without another way in, turning the password form off would lock everyone
      // out, the instance owner included.
      if (body.emailPassword === false && !sso) {
        throw new HttpError(400, 'Configure a single sign-on provider first');
      }
      const next = await setAuthSettings(body);
      return { ...next, hasEmailProvider: ready, hasSsoProvider: sso };
    },
    {
      body: AuthSettingsBody,
      response: { 200: AuthSettingsResponse, ...errors(400, 401, 403) },
      detail: {
        summary: 'Update authentication settings',
        description:
          'Update the instance registration mode, allowed email domains, invite lifetime and email-dependent auth options.',
      },
    },
  )

  .get('/god/email-settings', () => getEmailSettings(), {
    response: { 200: EmailSettingsResponse, ...errors(401, 403) },
    detail: {
      summary: 'Get instance email settings',
      description: 'Get the mail provider used for authentication email (secrets redacted).',
    },
  })

  .put('/god/email-settings', ({ body }) => setEmailSettings(body), {
    body: EmailSettingsBody,
    response: { 200: EmailSettingsResponse, ...errors(400, 401, 403) },
    detail: {
      summary: 'Update instance email settings',
      description: 'Update the mail provider used for authentication email.',
    },
  })

  .post(
    '/god/email-settings/test',
    async ({ user, body: patch }) => {
      const current = requireGod(user);
      if (!current.email) throw new HttpError(400, 'The instance owner has no email address');
      const config = await resolveEmailConfig(patch ?? {});
      if (!hasEmailProvider(config)) {
        throw new HttpError(400, 'Configure an email provider first');
      }

      await deliverTestEmail(config, {
        to: current.email,
        ...(await composeEmail('test', await emailLocale(current.email))),
      });
      return { recipient: current.email };
    },
    {
      body: t.Optional(EmailSettingsBody),
      response: { 200: EmailTestResponse, ...commonErrors, ...errors(502) },
      detail: {
        summary: 'Send a test email',
        description:
          'Send a test message through the supplied provider settings without saving them.',
      },
    },
  )

  .get('/god/email-templates', () => getEmailTemplates(), {
    response: { 200: EmailTemplatesResponse, ...errors(401, 403) },
    detail: {
      summary: 'Get email templates',
      description:
        'Get every email the instance sends, with its built-in texts and what god changed.',
    },
  })

  .put('/god/email-templates', ({ body }) => saveEmailTemplates(body), {
    body: EmailTemplatesBody,
    response: { 200: EmailTemplatesResponse, ...errors(400, 401, 403) },
    detail: {
      summary: 'Update email templates',
      description:
        'Replace the changed email texts and the layout. A null layout is the built-in one.',
    },
  })

  .post('/god/email-templates/preview', ({ body }) => previewEmail(body), {
    body: EmailDraftBody,
    response: { 200: EmailPreviewResponse, ...errors(400, 401, 403) },
    detail: {
      summary: 'Preview an email',
      description: 'Render an email from text and a layout, saved or not, with sample values.',
    },
  })

  .post(
    '/god/email-templates/test',
    ({ user, body }) => {
      const current = requireGod(user);
      if (!current.email) throw new HttpError(400, 'The instance owner has no email address');
      return sendTestEmail(current.email, body);
    },
    {
      body: EmailDraftBody,
      response: { 200: EmailTestResponse, ...commonErrors, ...errors(502) },
      detail: {
        summary: 'Send a test of an email',
        description: 'Send an email from text and a layout, saved or not, to the instance owner.',
      },
    },
  )

  .get(
    '/god/google-settings',
    async () => ({ ...(await getGoogleSettings()), redirectUri: GOOGLE_REDIRECT_URI }),
    {
      response: { 200: GoogleSettingsResponse, ...errors(401, 403) },
      detail: {
        summary: 'Get Google sign-in settings',
        description: 'Get the Google OAuth credentials (the client secret redacted).',
      },
    },
  )

  .put(
    '/god/google-settings',
    async ({ body }) => {
      const current = await getGoogleSettings();
      const enabled = body.enabled ?? current.enabled;
      const clientId = body.clientId ?? current.clientId;
      const hasClientSecret = (body.clientSecret?.length ?? 0) > 0 || current.hasClientSecret;
      // Turning it on without credentials would only offer a button that fails at
      // Google, so the same rule as the mail-dependent options applies here.
      if (enabled && (clientId.length === 0 || !hasClientSecret)) {
        throw new HttpError(400, 'Add the Google client ID and secret first');
      }
      await assertUsableSignInMethod(
        enabled && clientId.length > 0 && hasClientSecret,
        await hasConfiguredOidc(),
      );
      const next = await setGoogleSettings(body);
      return { ...next, redirectUri: GOOGLE_REDIRECT_URI };
    },
    {
      body: GoogleSettingsBody,
      response: { 200: GoogleSettingsResponse, ...errors(400, 401, 403) },
      detail: {
        summary: 'Update Google sign-in settings',
        description: 'Update the Google OAuth credentials and whether Google sign-in is offered.',
      },
    },
  )

  .get(
    '/god/oidc-settings',
    async () => ({ ...(await getOidcSettings()), redirectUri: OIDC_REDIRECT_URI }),
    {
      response: { 200: OidcSettingsResponse, ...errors(401, 403) },
      detail: {
        summary: 'Get OIDC sign-in settings',
        description: 'Get the generic OIDC/OAuth2 provider settings (the client secret redacted).',
      },
    },
  )

  .put(
    '/god/oidc-settings',
    async ({ body }) => {
      const current = await getOidcSettings();
      const enabled = body.enabled ?? current.enabled;
      const discoveryUrl = body.discoveryUrl ?? current.discoveryUrl;
      const clientId = body.clientId ?? current.clientId;
      const hasClientSecret = (body.clientSecret?.length ?? 0) > 0 || current.hasClientSecret;
      // Turning it on without credentials would only offer a button that fails at
      // the provider, the same rule the Google settings apply.
      if (enabled && (discoveryUrl.length === 0 || clientId.length === 0 || !hasClientSecret)) {
        throw new HttpError(400, 'Add the discovery URL, client ID and secret first');
      }
      await assertUsableSignInMethod(
        enabled && discoveryUrl.length > 0 && clientId.length > 0 && hasClientSecret,
        await hasConfiguredGoogle(),
      );
      const next = await setOidcSettings(body);
      return { ...next, redirectUri: OIDC_REDIRECT_URI };
    },
    {
      body: OidcSettingsBody,
      response: { 200: OidcSettingsResponse, ...errors(400, 401, 403) },
      detail: {
        summary: 'Update OIDC sign-in settings',
        description:
          'Update the generic OIDC/OAuth2 credentials and whether the provider is offered.',
      },
    },
  )

  .get('/god/scim', async () => ({ ...(await getScimSettings(null)), baseUrl: SCIM_BASE_URL }), {
    response: { 200: ScimSettingsResponse, ...errors(401, 403) },
    detail: {
      summary: 'Get SCIM provisioning settings',
      description: 'Get whether SCIM provisioning is on and whether a token has been generated.',
    },
  })

  .patch(
    '/god/scim',
    async ({ body }) => {
      // Enabling it without a token would leave the endpoint answering 401 to
      // everything, which reads as a broken integration rather than a missing step.
      if (body.enabled && !(await getScimSettings(null)).hasToken) {
        throw new HttpError(400, 'Generate a SCIM token first');
      }
      return { ...(await setScimSettings(null, body)), baseUrl: SCIM_BASE_URL };
    },
    {
      body: ScimSettingsBody,
      response: { 200: ScimSettingsResponse, ...errors(400, 401, 403) },
      detail: {
        summary: 'Update SCIM provisioning settings',
        description: 'Turn SCIM provisioning on or off.',
      },
    },
  )

  .post('/god/scim/token', async () => ({ token: await rotateScimToken(null) }), {
    response: { 200: ScimTokenResponse, ...errors(401, 403) },
    detail: {
      summary: 'Generate a SCIM token',
      description:
        'Generate the bearer token an identity provider sends to /scim/v2, replacing any ' +
        'previous one. The value is returned once and cannot be read back.',
    },
  })

  .get('/god/scim/groups', () => listProvisionedGroups(null), {
    response: { 200: t.Array(ProvisionedGroupResponse), ...errors(401, 403) },
    detail: {
      summary: 'List provisioned groups',
      description:
        "The groups the instance's identity provider has pushed, with their member counts and " +
        'the projects they grant membership in.',
    },
  })

  .put(
    '/god/scim/groups/:groupId/mappings',
    ({ params, body }) => setGroupMappings(null, params.groupId, body.mappings),
    {
      params: scimGroupParams,
      body: ScimGroupMappingsBody,
      response: { 200: ProvisionedGroupResponse, ...errors(400, 401, 403, 404) },
      detail: {
        summary: "Set a group's project mappings",
        description:
          'Replace the projects a provisioned group grants membership in, then reconcile the ' +
          'membership of every project the change touched.',
      },
    },
  )

  .get('/god/scim/projects', () => listMappableProjects(null), {
    response: { 200: MappableProjectListResponse, ...errors(401, 403) },
    detail: {
      summary: 'List mappable projects',
      description:
        'Every project a provisioned group may grant, with the roles its team assigns, for ' +
        'the group mapping picker.',
    },
  })

  .get('/god/storage-settings', () => getStorageSettings(), {
    response: { 200: StorageSettingsSchema, ...errors(401, 403) },
    detail: {
      summary: 'Get storage limits',
      description: 'Get the instance upload limits: file sizes, accepted types, and project quota.',
    },
  })

  .put('/god/storage-settings', ({ body }) => setStorageSettings(body), {
    body: StorageSettingsBody,
    response: { 200: StorageSettingsSchema, ...errors(400, 401, 403) },
    detail: {
      summary: 'Update storage limits',
      description:
        'Update the instance upload limits. They apply to new uploads only; files already stored are untouched.',
    },
  })

  .get('/god/project-defaults', () => getProjectDefaults(), {
    response: { 200: ProjectDefaultsSchema, ...errors(401, 403) },
    detail: {
      summary: 'Get project defaults',
      description: 'Get what a newly created project starts with on this instance.',
    },
  })

  .put('/god/project-defaults', ({ body }) => setProjectDefaults(body), {
    body: ProjectDefaultsSchema,
    response: { 200: ProjectDefaultsSchema, ...errors(400, 401, 403) },
    detail: {
      summary: 'Update project defaults',
      description:
        'Update what a newly created project starts with. Projects that already exist are untouched; each setting stays editable per project.',
    },
  })

  .get('/god/agent-settings', () => getAgentSettings(), {
    response: { 200: AgentSettingsSchema, ...errors(401, 403) },
    detail: {
      summary: 'Get instance agent settings',
      description: "Get what applies to every team's agents on this instance.",
    },
  })

  .put('/god/agent-settings', ({ body }) => setAgentSettings(body), {
    body: t.Partial(AgentSettingsSchema),
    response: { 200: AgentSettingsSchema, ...errors(400, 401, 403) },
    detail: {
      summary: 'Update instance agent settings',
      description:
        "Update what applies to every team's agents. A shorter trace retention takes effect " +
        'on the next sweep, which deletes the traces already past it.',
    },
  })

  .get('/god/sharing-settings', () => getSharingSettings(), {
    response: { 200: SharingSettingsSchema, ...errors(401, 403) },
    detail: {
      summary: 'Get instance sharing settings',
      description: 'Get whether public links work on this instance.',
    },
  })

  .put('/god/sharing-settings', ({ body }) => setSharingSettings(body), {
    body: SharingSettingsSchema,
    response: { 200: SharingSettingsSchema, ...errors(400, 401, 403) },
    detail: {
      summary: 'Update instance sharing settings',
      description:
        'Turn public links on or off for the whole instance. Off closes every link and ' +
        'refuses a new one; on opens the same links again, as each workspace allows.',
    },
  })

  .get('/god/hotkey-settings', () => getHotkeySettings(), {
    response: { 200: HotkeyCombosSchema, ...errors(401, 403) },
    detail: {
      summary: 'Get instance keyboard shortcuts',
      description:
        'Get the keyboard shortcut overrides that apply to everyone on this instance. A command left out uses the built-in binding.',
    },
  })

  .put('/god/hotkey-settings', ({ body }) => setHotkeySettings(body), {
    body: HotkeyCombosSchema,
    response: { 200: HotkeyCombosSchema, ...errors(400, 401, 403) },
    detail: {
      summary: 'Update instance keyboard shortcuts',
      description:
        'Replace the instance keyboard shortcut overrides. Each user may still rebind a shortcut for their own account.',
    },
  })

  .get('/god/embed-sites', () => getEmbedSites(), {
    response: { 200: EmbedSitesSchema, ...errors(401, 403) },
    detail: {
      summary: 'Get the sites that may embed public pages',
      description:
        'Get the sites that may show the shared work items and views, and the public pages, in a frame.',
    },
  })

  .put('/god/embed-sites', ({ body }) => setEmbedSites(body.origins), {
    body: EmbedSitesSchema,
    response: { 200: EmbedSitesSchema, ...errors(400, 401, 403) },
    detail: {
      summary: 'Set the sites that may embed public pages',
      description:
        'Replace the list. Each entry is a site address with no path; it is stored as its ' +
        'origin. Every other site, and every other page, is refused a frame.',
    },
  })

  // Whether a newer release is published, and the notes of the releases around the
  // running one. Owner-only: they are the one who upgrades the instance, and the
  // sidebar hides the indicator from everyone else. The version alone is readable by
  // any signed-in user (/settings/version).
  .get('/god/updates', () => getUpdateStatus(), {
    response: { 200: UpdateStatusSchema, ...errors(401, 403) },
    detail: {
      summary: 'Get the update status',
      description:
        'Get the running version, the newest published one, and the release notes. Every call reads the published releases upstream.',
    },
  })

  .post('/god/updates/check', () => getUpdateStatus(true), {
    response: { 200: UpdateStatusSchema, ...errors(401, 403) },
    detail: {
      summary: 'Check for updates now',
      description:
        'Read the published releases on demand. Returns the update status either way: a failed check answers from the release history of this build.',
    },
  })

  .get('/god/telegram-settings', () => getInstanceBotSettings(), {
    response: { 200: TelegramSettingsResponse, ...errors(401, 403) },
    detail: {
      summary: 'Get Telegram bot settings',
      description: 'Get the instance Telegram bot (the token redacted).',
    },
  })

  .put(
    '/god/telegram-settings',
    async ({ body }) => {
      const current = await getInstanceBotSettings();
      const hasBotToken = (body.botToken?.length ?? 0) > 0 || current.hasBotToken;
      // Without a token the bot can neither link accounts nor deliver, so turning it
      // on would only offer a button that leads nowhere.
      if (body.enabled && !hasBotToken) {
        throw new HttpError(400, 'Add the bot token first');
      }
      try {
        return await setInstanceBotSettings(body);
      } catch (err) {
        // A token Telegram rejects is the administrator's mistake, not a server
        // failure: report it as a bad request with what Telegram said.
        throw new HttpError(400, err instanceof Error ? err.message : 'Invalid bot token');
      }
    },
    {
      body: TelegramSettingsBody,
      response: { 200: TelegramSettingsResponse, ...errors(400, 401, 403) },
      detail: {
        summary: 'Update Telegram bot settings',
        description:
          'Update the instance Telegram bot token and whether the bot is in use. The token is verified with Telegram before it is stored.',
      },
    },
  )

  .get(
    '/god/users',
    ({ query }) =>
      paginate(query, (window) =>
        listInstanceUsers({ search: query.search, kind: query.kind ?? 'human', ...window }),
      ),
    {
      query: listUsersQuery,
      response: { 200: InstanceUserPageResponse, ...errors(400, 401, 403) },
      detail: {
        summary: 'List instance users',
        description:
          'One page of accounts, with the global role and sign-in state of each, plus how many match the filters.',
      },
    },
  )

  .get(
    '/god/users/:userId',
    async ({ params }) => {
      const found = await getInstanceUser(params.userId);
      if (!found) throw new HttpError(404, 'User not found');
      return found;
    },
    {
      params: userParams,
      response: { 200: InstanceUserDetailResponse, ...accessErrors },
      detail: {
        summary: 'Get an instance user',
        description:
          'Get one account with the projects it can reach and the permissions its membership resolves to.',
      },
    },
  )

  .post(
    '/god/users/:userId/verify-email',
    async ({ params }) => {
      const updated = await verifyInstanceUserEmail(params.userId);
      if (!updated) throw new HttpError(404, 'User not found');
      return updated;
    },
    {
      params: userParams,
      response: { 200: InstanceUserDetailResponse, ...accessErrors },
      detail: {
        summary: 'Confirm a user email address',
        description:
          'Mark an account as email-confirmed without the user opening a confirmation link.',
      },
    },
  )

  .post(
    '/god/users/:userId/deactivate',
    async ({ params }) => {
      const target = await getInstanceUser(params.userId);
      if (!target) throw new HttpError(404, 'User not found');
      assertActiveSwitchable(target.activeLock);
      const updated = await setInstanceUserActive(params.userId, false);
      if (!updated) throw new HttpError(404, 'User not found');
      return updated;
    },
    {
      params: userParams,
      response: { 200: InstanceUserDetailResponse, ...errors(401, 403, 404, 409) },
      detail: {
        summary: 'Deactivate a user',
        description:
          'Cut off an account without deleting it: end its sessions, revoke its MCP OAuth ' +
          'tokens and pending invites, and refuse its sign-ins and API keys until it is ' +
          'reactivated. Refused with 409 while a SCIM provider manages accounts.',
      },
    },
  )

  .post(
    '/god/users/:userId/reactivate',
    async ({ params }) => {
      const target = await getInstanceUser(params.userId);
      if (!target) throw new HttpError(404, 'User not found');
      assertActiveSwitchable(target.activeLock);
      const updated = await setInstanceUserActive(params.userId, true);
      if (!updated) throw new HttpError(404, 'User not found');
      return updated;
    },
    {
      params: userParams,
      response: { 200: InstanceUserDetailResponse, ...errors(401, 403, 404, 409) },
      detail: {
        summary: 'Reactivate a user',
        description:
          'Lift a deactivation so the account can sign in again and its API keys work. ' +
          'Refused with 409 while a SCIM provider manages accounts.',
      },
    },
  )

  .delete(
    '/god/users/:userId',
    async ({ params, query }) => {
      const target = await getInstanceUser(params.userId);
      if (!target) throw new HttpError(404, 'User not found');
      // An instance owner is not removable here: the role is what grants god mode,
      // so deleting one from inside it is how an instance loses its administration.
      if (target.role === 'god') throw new HttpError(403, 'An instance owner cannot be deleted');
      // An agent's bot user is created and removed with its AI Agent config.
      if (target.isAgent) {
        throw new HttpError(400, 'Delete the AI agent from its project instead');
      }
      // Projects this user owns alone outside the workspaces they own. Their membership
      // goes with the account, so the project would be left with nobody who can manage
      // it (god mode does not bypass project membership). Either the caller takes those
      // projects down with the account, or the request is refused until another owner is
      // added. The ones in their own workspaces pass to the instance owner with it.
      const sole = target.projects.filter(
        (p) => p.role === 'owner' && p.ownerCount === 1 && !p.inOwnWorkspace,
      );
      if (sole.length > 0 && !query.withProjects) {
        throw new HttpError(
          400,
          `This user is the only owner of ${sole.map((p) => p.projectKey).join(', ')}. Add another owner first, or delete the projects with the account.`,
        );
      }
      if (query.withProjects) {
        for (const p of sole) await deleteProject(p.projectId);
      }
      await deleteInstanceUser(params.userId);
      return noContent();
    },
    {
      params: userParams,
      query: deleteUserQuery,
      response: { 204: t.Void(), ...commonErrors },
      detail: {
        summary: 'Delete a user',
        description:
          'Remove an account from the instance, with its sessions, memberships and preferences. Optionally deletes the projects it owns alone; a workspace it owns goes with it while it holds no project or AI agent, and passes to the instance owner otherwise.',
      },
    },
  )

  .get(
    '/god/projects',
    ({ query }) =>
      paginate(query, (window) => listInstanceProjects({ search: query.search, ...window })),
    {
      query: searchPageQuery,
      response: { 200: InstanceProjectPageResponse, ...errors(400, 401, 403) },
      detail: {
        summary: 'List instance projects',
        description: 'One page of projects with what each holds, plus how many match the search.',
      },
    },
  )

  .get(
    '/god/projects/:projectId',
    async ({ params }) => {
      const found = await getInstanceProject(params.projectId);
      if (!found) throw new HttpError(404, 'Project not found');
      return found;
    },
    {
      params: projectParams,
      response: { 200: InstanceProjectDetailResponse, ...commonErrors },
      detail: {
        summary: 'Get an instance project',
        description:
          'Get one project with what it holds and every member, with the permissions each membership resolves to.',
      },
    },
  )

  .get(
    '/god/teams',
    ({ query }) =>
      paginate(query, (window) => listInstanceTeams({ search: query.search, ...window })),
    {
      query: searchPageQuery,
      response: { 200: InstanceTeamPageResponse, ...errors(400, 401, 403) },
      detail: {
        summary: 'List instance teams',
        description: 'One page of teams with what each holds, plus how many match the search.',
      },
    },
  )

  .get(
    '/god/teams/:teamId',
    async ({ params }) => {
      const found = await getInstanceTeam(params.teamId);
      if (!found) throw new HttpError(404, 'Team not found');
      return found;
    },
    {
      params: teamParams,
      response: { 200: InstanceTeamResponse, ...commonErrors },
      detail: {
        summary: 'Get an instance team',
        description: 'Get one team with what it holds. Its projects and members are paged apart.',
      },
    },
  )

  .get(
    '/god/teams/:teamId/projects',
    ({ params, query }) =>
      paginate(query, (window) =>
        listInstanceTeamProjects(params.teamId, { search: query.search, ...window }),
      ),
    {
      params: teamParams,
      query: searchPageQuery,
      response: { 200: InstanceTeamProjectPageResponse, ...commonErrors },
      detail: {
        summary: "List a team's projects",
        description: 'One page of the projects a team owns, with what each holds.',
      },
    },
  )

  .get(
    '/god/teams/:teamId/members',
    ({ params, query }) =>
      paginate(query, (window) =>
        listInstanceTeamMembers(params.teamId, { search: query.search, ...window }),
      ),
    {
      params: teamParams,
      query: searchPageQuery,
      response: { 200: InstanceTeamMemberPageResponse, ...commonErrors },
      detail: {
        summary: "List a team's members",
        description: 'One page of the team members, people and agents alike, with their rank.',
      },
    },
  )

  // System roles: permission matrices that belong to no team. Only god mode writes them.
  .get('/god/roles', () => listRoles(null), {
    response: { 200: t.Array(RoleResponse), ...errors(401, 403) },
    detail: { summary: 'List system roles', description: 'Every system role, oldest first.' },
  })

  .post(
    '/god/roles',
    async ({ body, set }) => {
      try {
        set.status = 201;
        return await createRole(null, body);
      } catch (err) {
        rethrowDuplicate(err, 'role');
      }
    },
    {
      body: createRoleBody,
      response: { 201: RoleResponse, ...errors(400, 401, 403, 409) },
      detail: { summary: 'Create a system role', description: 'Create a system role.' },
    },
  )

  .patch(
    '/god/roles/:roleId',
    async ({ params, body }) => {
      let role;
      try {
        role = await updateRole(null, params.roleId, body);
      } catch (err) {
        rethrowDuplicate(err, 'role');
      }
      if (!role) throw new HttpError(404, 'Role not found');
      return role;
    },
    {
      params: roleParams,
      body: updateRoleBody,
      response: { 200: RoleResponse, ...commonErrors, ...errors(409) },
      detail: {
        summary: 'Update a system role',
        description: 'Update the name or the permission matrix of a system role.',
      },
    },
  )

  .delete(
    '/god/roles/:roleId',
    async ({ params }) => {
      const role = await getRole(null, params.roleId);
      if (!role) throw new HttpError(404, 'Role not found');
      if (role.isDefault) throw new HttpError(400, 'The default role cannot be deleted');
      // Deleting a role in use would drop its holders onto the default matrix.
      if (isRoleInUse(await getRoleUsage(params.roleId))) {
        throw new HttpError(409, 'This role is in use');
      }
      await deleteRole(null, params.roleId, null);
      return noContent();
    },
    {
      params: roleParams,
      response: { 204: t.Void(), ...commonErrors, ...errors(409) },
      detail: {
        summary: 'Delete a system role',
        description: 'Delete a system role. The default role cannot be deleted.',
      },
    },
  );