@contember/cli 2.1.0-rc.3 → 2.2.0-alpha.10

package/src/commands/tenant/person/TenantIdentityRoleRemoveCommand.ts

@@ -0,0 +1,54 @@
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { requireConfirmation } from '../../../lib/tenant/confirmation.js'
+import { humanText } from '../tenantOutput.js'
+
+type Args = {
+	identityId: string
+	role: string[]
+}
+
+type Options = {
+	yes?: boolean
+}
+
+interface IdentityRolesResult {
+	identityId: string
+	removed: string[]
+	/** All global roles of the identity after the change, or null when the token may not read them. */
+	roles: string[] | null
+}
+
+export class TenantIdentityRoleRemoveCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Revoke global (project-independent) roles from an identity.')
+		configuration.argument('identityId').description('Identity id, as listed by "tenant person list".')
+		configuration.argument('role').variadic().description('One or more global roles to revoke.')
+		configuration.option('yes').valueNone().description('Do not ask for confirmation.')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const identityId = input.getArgument('identityId')
+		const removed = input.getArgument('role')
+
+		await requireConfirmation({
+			yes: input.getOption('yes') === true,
+			output,
+			warning: `This will revoke ${removed.join(', ')} from identity ${identityId}, which may lock it out of the API.`,
+		})
+
+		const roles = await this.tenantClientProvider.person().removeGlobalIdentityRoles(identityId, removed)
+
+		output.info(`Revoked ${removed.join(', ')} from identity ${identityId}.`)
+		output.data<IdentityRolesResult>(
+			{ identityId, removed, roles },
+			{ human: it => it.roles === null ? humanText(it.identityId) : it.roles.map(humanText).join(', '), quiet: it => it.identityId },
+		)
+	}
+}

package/src/commands/tenant/person/TenantPersonCreateCommand.ts

@@ -0,0 +1,98 @@
+import { CliError, Command, CommandConfiguration, ExitCode, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { TenantPerson } from '../../../lib/tenant/clients/TenantPersonClient.js'
+import { assertBcryptHash, type CaptchaTokenOptions, configureCaptchaTokenOptions, resolveCaptchaToken, resolveSecret } from './personInput.js'
+import { humanText, requireNonEmptyTenantName } from '../tenantOutput.js'
+import { readStdinText, StdinReader } from '../../../lib/tenant/stdin.js'
+
+type Args = {
+	email: string
+}
+
+type Options = CaptchaTokenOptions & {
+	name?: string
+	role?: string[]
+	['password-stdin']?: boolean
+	['password-env']?: string
+	['password-hash-stdin']?: boolean
+	['password-hash-env']?: string
+}
+
+export class TenantPersonCreateCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+		private readonly readStdin: StdinReader = readStdinText,
+		private readonly readEnvironment: (name: string) => string | undefined = name => process.env[name],
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description(
+			'Create a person (tenant signUp). Consumes the per-IP sign-up rate limit (config rateLimits.signUpPerIp, disabled by default, '
+				+ 'so bulk creation only throttles once a tenant configures it), verifies a captcha when one is configured, and sends a '
+				+ 'verification e-mail when signup.requireEmailVerification is on.',
+		)
+		configuration.argument('email').description('E-mail address of the new person.')
+		configuration.option('name').valueRequired().description('Display name of the new person.')
+		configuration.option('role').valueArray().description('Global identity role to grant. Repeat the option to grant several.')
+		configuration.option('password-stdin').valueNone().description('Read the plaintext password from stdin.')
+		configuration.option('password-env').valueRequired().description('Read the plaintext password from the named environment variable.')
+		configuration.option('password-hash-stdin').valueNone().description('Read a bcrypt ($2b$) password hash from stdin.')
+		configuration.option('password-hash-env').valueRequired().description(
+			'Read a bcrypt ($2b$) password hash from the named environment variable. Preferred for provisioning — the plaintext never leaves your side.',
+		)
+		configureCaptchaTokenOptions(configuration)
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const email = input.getArgument('email')
+		const name = requireNonEmptyTenantName(input.getOption('name'), 'Person')
+		const passwordFromStdin = input.getOption('password-stdin') === true
+		const passwordHashFromStdin = input.getOption('password-hash-stdin') === true
+		const captchaFromStdin = input.getOption('captcha-token-stdin') === true
+		if (captchaFromStdin && (passwordFromStdin || passwordHashFromStdin)) {
+			throw new CliError('Only one value can consume stdin. Combine a --*-stdin option with an environment-backed source instead.', {
+				code: 'AMBIGUOUS_STDIN_INPUT',
+				exitCode: ExitCode.InputError,
+			})
+		}
+		const secret = await resolveSecret(
+			[
+				{ name: 'password', stdin: passwordFromStdin, env: input.getOption('password-env') },
+				{ name: 'password-hash', stdin: passwordHashFromStdin, env: input.getOption('password-hash-env') },
+			],
+			this.readStdin,
+		)
+		const password = secret?.name === 'password' ? secret.value : undefined
+		const passwordHash = secret?.name === 'password-hash' ? secret.value : undefined
+		if (passwordHash !== undefined) {
+			assertBcryptHash(passwordHash)
+		}
+		if (secret === undefined) {
+			output.warn('No password given. The person is created without one and can only sign in after a password reset or through an identity provider.')
+		}
+		const captchaToken = await resolveCaptchaToken(
+			{
+				'captcha-token': input.getOption('captcha-token'),
+				'captcha-token-env': input.getOption('captcha-token-env'),
+				'captcha-token-stdin': input.getOption('captcha-token-stdin'),
+			},
+			this.readStdin,
+			this.readEnvironment,
+		)
+
+		output.info(`Creating person ${email}`)
+		const person = await this.tenantClientProvider.person().signUp({
+			email,
+			password,
+			passwordHash,
+			name,
+			roles: input.getOption('role'),
+			captchaToken,
+		})
+
+		output.info(`Created person ${person.id} with identity ${person.identityId}.`)
+		output.data<TenantPerson>(person, { human: it => humanText(it.id), quiet: it => it.id })
+	}
+}

package/src/commands/tenant/person/TenantPersonDisableCommand.ts

@@ -0,0 +1,46 @@
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { requireConfirmation } from '../../../lib/tenant/confirmation.js'
+import { humanText } from '../tenantOutput.js'
+
+type Args = {
+	id: string
+}
+
+type Options = {
+	yes?: boolean
+}
+
+interface DisableResult {
+	personId: string
+	disabled: true
+}
+
+export class TenantPersonDisableCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Disable a person. They can no longer sign in and all of their API keys are invalidated.')
+		configuration.argument('id').description('Person id.')
+		configuration.option('yes').valueNone().description('Do not ask for confirmation.')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const personId = input.getArgument('id')
+
+		await requireConfirmation({
+			yes: input.getOption('yes') === true,
+			output,
+			warning: `This will disable person ${personId} and invalidate all of their API keys.`,
+		})
+
+		await this.tenantClientProvider.person().disablePerson(personId)
+
+		output.info(`Person ${personId} was disabled.`)
+		output.data<DisableResult>({ personId, disabled: true }, { human: it => humanText(it.personId), quiet: it => it.personId })
+	}
+}

package/src/commands/tenant/person/TenantPersonListCommand.ts

@@ -0,0 +1,68 @@
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { PersonsFilter } from '@contember/graphql-client-tenant'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { TenantPerson } from '../../../lib/tenant/clients/TenantPersonClient.js'
+import { parsePaginationLimit, parsePaginationOffset } from '../../../lib/tenant/input/pagination.js'
+
+type Args = {}
+
+type Options = {
+	email?: string
+	['person-id']?: string
+	['identity-id']?: string
+	limit?: string
+	offset?: string
+}
+
+export class TenantPersonListCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description(
+			'List persons. A SUPER_ADMIN sees everyone, anyone else only the members of projects they may view members of.',
+		)
+		configuration.option('email').valueRequired().description('Filter by e-mail address (case-insensitive substring match).')
+		configuration.option('person-id').valueRequired().description('Filter by person id.')
+		configuration.option('identity-id').valueRequired().description('Filter by identity id.')
+		configuration.option('limit').valueRequired().description(
+			'Page size. The server caps it (default 100, max 1000) — this command never paginates behind your back.',
+		)
+		configuration.option('offset').valueRequired().description('Number of persons to skip. Combine with --limit to page through the list.')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const filter: PersonsFilter = {
+			email: input.getOption('email'),
+			personId: input.getOption('person-id'),
+			identityId: input.getOption('identity-id'),
+		}
+		const hasFilter = filter.email !== undefined || filter.personId !== undefined || filter.identityId !== undefined
+
+		const persons = await this.tenantClientProvider.person().listPersons({
+			filter: hasFilter ? filter : undefined,
+			limit: parsePaginationLimit(input.getOption('limit')),
+			offset: parsePaginationOffset(input.getOption('offset')),
+		})
+
+		if (persons.length === 0) {
+			output.info('No persons matched.')
+		}
+		output.table<TenantPerson>(
+			[
+				{ field: 'id', name: 'ID' },
+				{ field: 'email', name: 'E-mail' },
+				{ field: 'name', name: 'Name' },
+				{ field: 'identityId', name: 'Identity' },
+				{ field: 'otpEnabled', name: 'TOTP' },
+				{ field: 'emailOtpEnabled', name: 'E-mail OTP' },
+				{ field: 'emailVerified', name: 'Verified' },
+			],
+			persons,
+			'id',
+		)
+	}
+}

package/src/commands/tenant/person/TenantPersonResetMfaCommand.ts

@@ -0,0 +1,59 @@
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { requireConfirmation } from '../../../lib/tenant/confirmation.js'
+import { humanText } from '../tenantOutput.js'
+
+type Args = {
+	id: string
+}
+
+type Options = {
+	yes?: boolean
+}
+
+/** Spells out every factor the server clears, so an incident report can be written straight off this payload. */
+interface ResetMfaResult {
+	personId: string
+	mfaReset: true
+	totpDisabled: true
+	emailOtpDisabled: true
+	backupCodesDeleted: true
+}
+
+export class TenantPersonResetMfaCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description(
+			'Reset every MFA factor of a locked-out person: active and pending TOTP, e-mail OTP, and their backup codes. '
+				+ 'The person can enroll again afterwards. An account-recovery operation, recorded in the auth log.',
+		)
+		configuration.argument('id').description('Person id.')
+		configuration.option('yes').valueNone().description('Do not ask for confirmation.')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const personId = input.getArgument('id')
+
+		await requireConfirmation({
+			yes: input.getOption('yes') === true,
+			output,
+			warning: `This will remove TOTP, e-mail OTP and the backup codes of person ${personId}, leaving the account without a second factor.`,
+		})
+
+		await this.tenantClientProvider.person().resetPersonMfa(personId)
+
+		output.info(`MFA of person ${personId} was reset: TOTP and e-mail OTP disabled, backup codes deleted.`)
+		output.data<ResetMfaResult>({
+			personId,
+			mfaReset: true,
+			totpDisabled: true,
+			emailOtpDisabled: true,
+			backupCodesDeleted: true,
+		}, { human: it => humanText(it.personId), quiet: it => it.personId })
+	}
+}

package/src/commands/tenant/person/TenantPersonResetPasswordRequestCommand.ts

@@ -0,0 +1,67 @@
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { readStdinText, type StdinReader } from '../../../lib/tenant/stdin.js'
+import { type CaptchaTokenOptions, configureCaptchaTokenOptions, resolveCaptchaToken } from './personInput.js'
+import { humanText } from '../tenantOutput.js'
+
+type Args = {
+	email: string
+}
+
+type Options = CaptchaTokenOptions & {
+	['mail-project']?: string
+	['mail-variant']?: string
+}
+
+interface ResetPasswordRequestResult {
+	email: string
+	requested: true
+	mailProject: string | null
+	mailVariant: string | null
+}
+
+export class TenantPersonResetPasswordRequestCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+		private readonly readStdin: StdinReader = readStdinText,
+		private readonly readEnvironment: (name: string) => string | undefined = name => process.env[name],
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description(
+			'Send a password-reset e-mail to an address. Consumes the per-IP password-reset rate limit (config rateLimits.passwordResetPerIp, '
+				+ 'disabled by default) and reports success even for an unknown address, unless the tenant enables login.revealUserExists.',
+		)
+		configuration.argument('email').description('E-mail address of the person to send the reset link to.')
+		configuration.option('mail-project').valueRequired().description('Project slug whose mail template variant is used.')
+		configuration.option('mail-variant').valueRequired().description('Mail template variant, usually a locale.')
+		configureCaptchaTokenOptions(configuration)
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const email = input.getArgument('email')
+		const mailProject = input.getOption('mail-project')
+		const mailVariant = input.getOption('mail-variant')
+		const captchaToken = await resolveCaptchaToken(
+			{
+				'captcha-token': input.getOption('captcha-token'),
+				'captcha-token-env': input.getOption('captcha-token-env'),
+				'captcha-token-stdin': input.getOption('captcha-token-stdin'),
+			},
+			this.readStdin,
+			this.readEnvironment,
+		)
+
+		await this.tenantClientProvider.person().createResetPasswordRequest(email, { mailProject, mailVariant }, captchaToken)
+
+		output.info(`Password reset requested for ${email}. An unknown address is reported as success too, so this is not proof the person exists.`)
+		output.data<ResetPasswordRequestResult>({
+			email,
+			requested: true,
+			mailProject: mailProject ?? null,
+			mailVariant: mailVariant ?? null,
+		}, { human: it => humanText(it.email), quiet: it => it.email })
+	}
+}

package/src/commands/tenant/person/TenantPersonSetPasswordCommand.ts

@@ -0,0 +1,66 @@
+import { CliError, Command, CommandConfiguration, ExitCode, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { resolveSecret } from './personInput.js'
+import { requireConfirmation } from '../../../lib/tenant/confirmation.js'
+import { humanText } from '../tenantOutput.js'
+import { readStdinText, StdinReader } from '../../../lib/tenant/stdin.js'
+
+type Args = {
+	id: string
+}
+
+type Options = {
+	['password-stdin']?: boolean
+	['password-env']?: string
+	yes?: boolean
+}
+
+interface SetPasswordResult {
+	personId: string
+	passwordChanged: true
+}
+
+export class TenantPersonSetPasswordCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+		private readonly readStdin: StdinReader = readStdinText,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description(
+			'Set the password of a person. The new password is read from stdin or from an environment variable, never from the command line, '
+				+ 'which would leak it into the shell history and into `ps`. The tenant password policy still applies.',
+		)
+		configuration.argument('id').description('Person id.')
+		configuration.option('password-stdin').valueNone().description('Read the new plaintext password from stdin.')
+		configuration.option('password-env').valueRequired().description('Read the new plaintext password from the named environment variable.')
+		configuration.option('yes').valueNone().description('Do not ask for confirmation.')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const personId = input.getArgument('id')
+		const secret = await resolveSecret(
+			[{ name: 'password', stdin: input.getOption('password-stdin') === true, env: input.getOption('password-env') }],
+			this.readStdin,
+		)
+		if (secret === undefined) {
+			throw new CliError('No password given. Pass --password-stdin or --password-env <VARIABLE>.', {
+				code: 'PASSWORD_REQUIRED',
+				exitCode: ExitCode.InputError,
+			})
+		}
+
+		await requireConfirmation({
+			yes: input.getOption('yes') === true,
+			output,
+			warning: `This will replace the password of person ${personId}.`,
+		})
+
+		await this.tenantClientProvider.person().changePassword(personId, secret.value)
+
+		output.info(`Password of person ${personId} was changed.`)
+		output.data<SetPasswordResult>({ personId, passwordChanged: true }, { human: it => humanText(it.personId), quiet: it => it.personId })
+	}
+}

package/src/commands/tenant/person/TenantPersonShowCommand.ts

@@ -0,0 +1,70 @@
+import { CliError, Command, CommandConfiguration, ExitCode, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { TenantPersonDetail } from '../../../lib/tenant/clients/TenantPersonClient.js'
+import { humanText } from '../tenantOutput.js'
+
+type Args = {
+	id: string
+}
+
+type Options = {}
+
+/** Renders the whole record as an indented block. */
+const formatPersonDetail = (person: TenantPersonDetail): string => {
+	const lines = [
+		`Person:       ${humanText(person.id)}`,
+		`Identity:     ${humanText(person.identityId)}`,
+		`E-mail:       ${person.email === null ? '-' : humanText(person.email)} (${person.emailVerified ? 'verified' : 'unverified'})`,
+		`Name:         ${person.name === null ? '-' : humanText(person.name)}`,
+		`Roles:        ${person.roles === null ? '(not visible)' : person.roles.map(humanText).join(', ') || '-'}`,
+		`TOTP:         ${person.otpEnabled ? 'enabled' : 'disabled'}`,
+		`E-mail OTP:   ${person.emailOtpEnabled ? 'enabled' : 'disabled'}`,
+		`Passwordless: ${person.passwordlessEnabled === null ? '(unset)' : person.passwordlessEnabled ? 'enabled' : 'disabled'}`,
+		`Sessions:     ${person.sessions.length === 0 ? 'none' : ''}`,
+	]
+	for (const session of person.sessions) {
+		lines.push(
+			`  ${humanText(session.id)}  created ${humanText(session.createdAt)}  last used ${
+				session.lastUsedAt === null ? '-' : humanText(session.lastUsedAt)
+			}  from ${session.lastIp === null ? '-' : humanText(session.lastIp)}  trust forwarded client info ${
+				session.trustForwardedClientInfo ? 'yes' : 'no'
+			}`,
+		)
+	}
+	lines.push(`Identity providers: ${person.identityProviders.length === 0 ? 'none' : ''}`)
+	for (const idp of person.identityProviders) {
+		lines.push(
+			`  ${humanText(idp.slug)} (${humanText(idp.type)})  external id ${humanText(idp.externalIdentifier)}  connected ${humanText(idp.createdAt)}`,
+		)
+	}
+	return lines.join('\n')
+}
+
+export class TenantPersonShowCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Show a single person with their roles, active sessions and identity provider connections.')
+		configuration.argument('id').description('Person id.')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const id = input.getArgument('id')
+		const person = await this.tenantClientProvider.person().getPerson(id)
+		if (person === null) {
+			// the API returns null for both cases and does not tell them apart, so neither can we
+			throw new CliError(`Person ${id} was not found, or you are not allowed to view them.`, {
+				code: 'PERSON_NOT_FOUND',
+				exitCode: ExitCode.NotFound,
+			})
+		}
+		if (person.roles === null) {
+			output.info('Roles are hidden: your token may not read the roles of this identity.')
+		}
+		output.data(person, { human: formatPersonDetail, quiet: it => it.id })
+	}
+}

package/src/commands/tenant/person/TenantPersonSignOutCommand.ts

@@ -0,0 +1,60 @@
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { requireConfirmation } from '../../../lib/tenant/confirmation.js'
+import { humanText } from '../tenantOutput.js'
+
+type Args = {
+	id: string
+}
+
+type Options = {
+	reason?: string
+	yes?: boolean
+}
+
+interface SignOutResult {
+	personId: string
+	signedOut: true
+	/** Recorded in the tenant auth log next to the sign-out event. */
+	reason: string | null
+}
+
+export class TenantPersonSignOutCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description(
+			'Force sign-out: revoke every active session and disable all attached API keys, including permanent keys. An account-recovery operation, recorded in the auth log.',
+		)
+		configuration.argument('id').description('Person id.')
+		configuration.option('reason').valueRequired().description('Reason stored with the auth log entry, e.g. an incident id.')
+		configuration.option('yes').valueNone().description('Do not ask for confirmation.')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const personId = input.getArgument('id')
+		const reason = input.getOption('reason')
+
+		await requireConfirmation({
+			yes: input.getOption('yes') === true,
+			output,
+			warning: `This will revoke every active session and disable all attached API keys of person ${personId}, including permanent keys.`,
+		})
+
+		await this.tenantClientProvider.person().forceSignOutPerson(personId, reason)
+
+		output.info(
+			`Every session of person ${personId} was revoked and all attached API keys, including permanent keys, were disabled${
+				reason !== undefined ? ` (reason: ${reason})` : ''
+			}.`,
+		)
+		output.data<SignOutResult>(
+			{ personId, signedOut: true, reason: reason ?? null },
+			{ human: it => humanText(it.personId), quiet: it => it.personId },
+		)
+	}
+}

package/src/commands/tenant/person/TenantPersonUpdateCommand.ts

@@ -0,0 +1,55 @@
+import { CliError, Command, CommandConfiguration, ExitCode, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { humanText, requireNonEmptyTenantName } from '../tenantOutput.js'
+
+type Args = {
+	id: string
+}
+
+type Options = {
+	email?: string
+	name?: string
+}
+
+interface UpdateResult {
+	personId: string
+	/** Null means the field was left alone — the API cannot clear an e-mail or a name. */
+	email: string | null
+	name: string | null
+}
+
+export class TenantPersonUpdateCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Change the profile of a person. Only the fields you pass are changed; neither can be cleared.')
+		configuration.argument('id').description('Person id.')
+		configuration.option('email').valueRequired().description('New e-mail address.')
+		configuration.option('name').valueRequired().description('New display name.')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const personId = input.getArgument('id')
+		const email = input.getOption('email')
+		const name = requireNonEmptyTenantName(input.getOption('name'), 'Person')
+		if (email === undefined && name === undefined) {
+			throw new CliError('Nothing to update. Pass --email, --name, or both.', {
+				code: 'NOTHING_TO_UPDATE',
+				exitCode: ExitCode.InputError,
+			})
+		}
+
+		await this.tenantClientProvider.person().changeProfile(personId, { email, name })
+
+		const changed = [email !== undefined ? 'e-mail' : null, name !== undefined ? 'name' : null].filter(it => it !== null)
+		output.info(`Updated ${changed.join(' and ')} of person ${personId}.`)
+		output.data<UpdateResult>(
+			{ personId, email: email ?? null, name: name ?? null },
+			{ human: it => humanText(it.personId), quiet: it => it.personId },
+		)
+	}
+}