@contember/cli 2.2.0-alpha.3 → 2.2.0-alpha.5

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 },
+		)
+	}
+}

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

@@ -0,0 +1,79 @@
+import { CliError, Command, CommandConfiguration, ExitCode, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import type { TenantCreatedSessionToken } from '../../../lib/tenant/clients/TenantPersonClient.js'
+import { assertGeneratedTenantToken, humanText } from '../tenantOutput.js'
+
+type Args = {}
+
+type Options = {
+	email?: string
+	['person-id']?: string
+	expiration?: string
+	['trust-forwarded-client-info']?: boolean
+}
+
+/** `tenant session create` */
+export class TenantSessionCreateCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Create a one-time session token for exactly one person. Requires person.createSessionToken permission.')
+		configuration.option('email').valueRequired().description('Identify the person by e-mail. Not combinable with --person-id.')
+		configuration.option('person-id').valueRequired().description('Identify the person by id. Not combinable with --email.')
+		configuration.option('expiration').valueRequired().description('Session lifetime in minutes as a positive integer.')
+		configuration.option('trust-forwarded-client-info').valueNone().description(
+			'Trust forwarded client IP and user-agent headers for this session only when the tenant endpoint is behind a trusted proxy.',
+		)
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const email = input.getOption('email')
+		const personId = input.getOption('person-id')
+		if ((email === undefined) === (personId === undefined)) {
+			throw new CliError('Pass exactly one of --email or --person-id.', {
+				code: 'INVALID_PERSON_IDENTIFIER',
+				exitCode: ExitCode.InputError,
+			})
+		}
+		if (email?.trim() === '' || personId?.trim() === '') {
+			throw new CliError('The value passed to --email or --person-id must not be empty.', {
+				code: 'INVALID_PERSON_IDENTIFIER',
+				exitCode: ExitCode.InputError,
+			})
+		}
+		const expiration = parsePositiveInteger(input.getOption('expiration'), 'expiration')
+		const trustForwardedClientInfo = input.getOption('trust-forwarded-client-info') === true
+
+		const result = await this.tenantClientProvider.person().createSessionToken({
+			email,
+			personId,
+			expiration,
+			options: trustForwardedClientInfo ? { trustForwardedClientInfo: true } : undefined,
+		})
+		const token = assertGeneratedTenantToken(result.token, 'session')
+
+		output.info(`Created a session token for person ${result.personId}. The token is shown once; store it securely.`)
+		output.data<TenantCreatedSessionToken>(result, {
+			human: it => `Session token for person ${humanText(it.personId)}:\n${token}`,
+			quiet: () => token,
+		})
+	}
+}
+
+const parsePositiveInteger = (value: string | undefined, option: string): number | undefined => {
+	if (value === undefined) {
+		return undefined
+	}
+	const parsed = Number(value)
+	if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 2_147_483_647) {
+		throw new CliError(`--${option} must be a positive GraphQL Int (maximum 2147483647).`, {
+			code: 'INVALID_OPTION_VALUE',
+			exitCode: ExitCode.InputError,
+		})
+	}
+	return parsed
+}

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

@@ -0,0 +1,15 @@
+// Commands of `tenant person`, plus `tenant session create` and `tenant identity role …` — the directory
+// maps to the TenantPersonClient domain (persons, sessions, global identity roles), not to a command prefix.
+// `personInput.ts` stays unexported on purpose: the five tenant barrels merge into `commands/tenant/index.ts`.
+export * from './TenantIdentityRoleAddCommand.js'
+export * from './TenantIdentityRoleRemoveCommand.js'
+export * from './TenantPersonCreateCommand.js'
+export * from './TenantPersonDisableCommand.js'
+export * from './TenantPersonListCommand.js'
+export * from './TenantPersonResetMfaCommand.js'
+export * from './TenantPersonResetPasswordRequestCommand.js'
+export * from './TenantPersonSetPasswordCommand.js'
+export * from './TenantPersonShowCommand.js'
+export * from './TenantPersonSignOutCommand.js'
+export * from './TenantPersonUpdateCommand.js'
+export * from './TenantSessionCreateCommand.js'

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

@@ -0,0 +1,112 @@
+import { CliError, ExitCode } from '@contember/cli-common'
+import type { StdinReader } from '../../../lib/tenant/stdin.js'
+import { environmentInput, literalInput, resolveOptionalTenantInput, stdinInput, type TenantInputSource } from '../../../lib/tenant/input/index.js'
+
+/**
+ * One way of passing a secret. `name` is the option prefix, so `password` covers `--password-stdin`
+ * and `--password-env`. A secret is never a plain option value — argv lands in the shell history and
+ * in `ps` output of every user on the machine.
+ */
+export interface SecretSource {
+	readonly name: string
+	readonly stdin: boolean
+	readonly env: string | undefined
+}
+
+export interface ResolvedSecret {
+	/** The `name` of the {@link SecretSource} the value came from. */
+	readonly name: string
+	readonly value: string
+}
+
+/** Resolves at most one of the offered secret sources. Returns undefined when the caller passed none. */
+export const resolveSecret = async (sources: readonly SecretSource[], readStdin: StdinReader): Promise<ResolvedSecret | undefined> => {
+	const given = sources.flatMap(source => [
+		...(source.stdin ? [{ source, flag: `--${source.name}-stdin` }] : []),
+		...(source.env !== undefined ? [{ source, flag: `--${source.name}-env` }] : []),
+	])
+	if (given.length > 1) {
+		throw new CliError(`Pass only one of ${given.map(it => it.flag).join(', ')}.`, {
+			code: 'AMBIGUOUS_SECRET_SOURCE',
+			exitCode: ExitCode.InputError,
+		})
+	}
+	const chosen = given[0]
+	if (chosen === undefined) {
+		return undefined
+	}
+	// the trailing newline `echo` adds is never part of the secret
+	const value = chosen.source.env !== undefined ? readSecretEnv(chosen.source.env) : (await readStdin()).replace(/\r?\n$/, '')
+	if (value === '') {
+		throw new CliError(`${chosen.flag} resolved to an empty value.`, { code: 'EMPTY_SECRET', exitCode: ExitCode.InputError })
+	}
+	return { name: chosen.source.name, value }
+}
+
+const readSecretEnv = (name: string): string => {
+	const value = process.env[name]
+	if (value === undefined) {
+		throw new CliError(`Environment variable ${name} is not set.`, { code: 'SECRET_ENV_NOT_SET', exitCode: ExitCode.InputError })
+	}
+	return value
+}
+
+/** The tenant API accepts `$2b$` bcrypt hashes only — rejecting here avoids spending a rate-limit slot on a doomed call. */
+export const assertBcryptHash = (hash: string): void => {
+	if (!hash.startsWith('$2b$')) {
+		throw new CliError('Invalid password hash: the tenant API accepts bcrypt $2b$ hashes only.', {
+			code: 'INVALID_PASSWORD_HASH',
+			exitCode: ExitCode.InputError,
+		})
+	}
+}
+
+export type CaptchaTokenOptions = {
+	readonly ['captcha-token']?: string
+	readonly ['captcha-token-env']?: string
+	readonly ['captcha-token-stdin']?: boolean
+}
+
+export const configureCaptchaTokenOptions = (configuration: {
+	option(name: keyof CaptchaTokenOptions): {
+		valueNone(): { description(description: string): unknown }
+		valueRequired(): { description(description: string): unknown }
+	}
+}): void => {
+	configuration.option('captcha-token').valueRequired().description(
+		'Captcha token. Visible in the shell history and process list; prefer --captcha-token-env or --captcha-token-stdin.',
+	)
+	configuration.option('captcha-token-env').valueRequired().description('Read the captcha token from the named environment variable.')
+	configuration.option('captcha-token-stdin').valueNone().description('Read the captcha token from stdin.')
+}
+
+export const resolveCaptchaToken = async (
+	options: CaptchaTokenOptions,
+	readStdin: StdinReader,
+	readEnvironment: (name: string) => string | undefined = name => process.env[name],
+): Promise<string | undefined> => {
+	const sources: TenantInputSource<'captcha-token'>[] = []
+	if (options['captcha-token'] !== undefined) {
+		sources.push(literalInput('captcha-token', '--captcha-token', options['captcha-token']))
+	}
+	if (options['captcha-token-env'] !== undefined) {
+		sources.push(environmentInput('captcha-token', '--captcha-token-env', options['captcha-token-env']))
+	}
+	if (options['captcha-token-stdin'] === true) {
+		sources.push(stdinInput('captcha-token', '--captcha-token-stdin'))
+	}
+	const resolved = await resolveOptionalTenantInput(sources, { label: 'captcha token' }, { readStdin, readEnvironment })
+	if (resolved === undefined) {
+		return undefined
+	}
+	const value = resolved.kind === 'stdin' ? removeOneTrailingLineEnding(resolved.value) : resolved.value
+	if (value === '') {
+		throw new CliError('The selected captcha token source resolved to an empty value.', {
+			code: 'EMPTY_INPUT_VALUE',
+			exitCode: ExitCode.InputError,
+		})
+	}
+	return value
+}
+
+const removeOneTrailingLineEnding = (value: string): string => value.replace(/(?:\r\n|\n)$/, '')