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

package/src/commands/tenant/policy/TenantAuthLogCommand.ts

@@ -0,0 +1,141 @@
+/// <reference path="../../../../types/chalk-table/index.d.ts" />
+
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import type { AuthLogFilter } from '@contember/graphql-client-tenant'
+import chalkTable from 'chalk-table'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { TenantAuthLogEntry } from '../../../lib/tenant/clients/index.js'
+import { GRAPHQL_INT_MAX, parsePaginationLimit, parsePaginationOffset } from '../../../lib/tenant/input/index.js'
+import { inputError } from './policyInput.js'
+import { humanText } from '../tenantOutput.js'
+
+type Args = {}
+
+type Options = {
+	type?: string[]
+	success?: boolean
+	failed?: boolean
+	['invoked-by']?: string
+	person?: string
+	['target-person']?: string
+	['person-input']?: string
+	['created-after']?: string
+	['created-before']?: string
+	limit?: string
+	offset?: string
+}
+
+/** The command's answer: the page plus everything a script needs to fetch the next one. */
+export interface AuthLogPageResult {
+	entries: TenantAuthLogEntry[]
+	/** True when rows exist past this page. */
+	hasMore: boolean
+	offset: number
+	/** Offset to pass to the next call, `null` when this is the last page. */
+	nextOffset: number | null
+}
+
+export class TenantAuthLogCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Read the tenant auth log (audit trail). Requires the system:viewAuthLog permission.')
+		configuration.option('type').valueArray().description('Filter by auth_log_type, e.g. sign_in. Repeat the option to match any of several types.')
+		configuration.option('success').valueNone().description('Only successful entries.')
+		configuration.option('failed').valueNone().description('Only failed entries.')
+		configuration.option('invoked-by').valueRequired().description('Filter by the acting identity id.')
+		configuration.option('person').valueRequired().description('Filter by the acting person id.')
+		configuration.option('target-person').valueRequired().description('Filter by the person the action was performed on.')
+		configuration.option('person-input').valueRequired().description('Filter by the submitted identifier, typically the e-mail of a failed sign-in.')
+		configuration.option('created-after').valueRequired().description('Inclusive lower bound on createdAt, as an ISO 8601 timestamp.')
+		configuration.option('created-before').valueRequired().description('Exclusive upper bound on createdAt, as an ISO 8601 timestamp.')
+		configuration.option('limit').valueRequired().description('Page size. Server default is 100, capped at 500.')
+		configuration.option('offset').valueRequired().description('Number of entries to skip. Use the nextOffset of the previous page.')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const limit = parsePaginationLimit(input.getOption('limit'))
+		const offset = parsePaginationOffset(input.getOption('offset')) ?? 0
+		const filter = this.readFilter(input)
+
+		const page = await this.tenantClientProvider.policy().readAuthLog({
+			filter: Object.values(filter).some(it => it !== undefined) ? filter : undefined,
+			limit,
+			offset,
+		})
+
+		const advancedOffset = offset + page.entries.length
+		const canContinue = page.hasMore && page.entries.length > 0 && advancedOffset <= GRAPHQL_INT_MAX
+		const result: AuthLogPageResult = {
+			entries: page.entries,
+			hasMore: canContinue,
+			offset,
+			nextOffset: canContinue ? advancedOffset : null,
+		}
+		output.info(`authLog: ${page.entries.length} entries from offset ${offset}${result.hasMore ? ', more available' : ''}`)
+		output.data(result, { human: renderHuman, quiet: value => value.entries.map(entry => entry.id) })
+	}
+
+	private readFilter(input: Input<Args, Options>): AuthLogFilter {
+		const successOnly = input.getOption('success') === true
+		const failedOnly = input.getOption('failed') === true
+		if (successOnly && failedOnly) {
+			throw inputError('Pass either --success or --failed, not both.', 'AMBIGUOUS_INPUT')
+		}
+		return {
+			types: input.getOption('type'),
+			success: successOnly ? true : failedOnly ? false : undefined,
+			invokedByIdentityId: input.getOption('invoked-by'),
+			personId: input.getOption('person'),
+			targetPersonId: input.getOption('target-person'),
+			personInputIdentifier: input.getOption('person-input'),
+			createdAfter: input.getOption('created-after'),
+			createdBefore: input.getOption('created-before'),
+		}
+	}
+}
+
+type AuthLogCell = 'createdAt' | 'type' | 'success' | 'person' | 'identity' | 'ip' | 'error'
+
+// A curated, narrow projection: the full entry (metadata, eventData, user agent) stays in --json.
+const humanColumns: { field: AuthLogCell; name: string }[] = [
+	{ field: 'createdAt', name: 'Time (UTC)' },
+	{ field: 'type', name: 'Type' },
+	{ field: 'success', name: 'OK' },
+	{ field: 'person', name: 'Person' },
+	{ field: 'identity', name: 'Identity' },
+	{ field: 'ip', name: 'IP' },
+	{ field: 'error', name: 'Error' },
+]
+
+/**
+ * `Output.data` renders the human view, because `Output.table` can only emit a bare array and the
+ * paging fields have to stay in the `--json` payload. Formatting therefore lives here, human-only.
+ */
+const renderHuman = (page: AuthLogPageResult): string => {
+	if (page.entries.length === 0) {
+		return 'No auth log entries match the filter.'
+	}
+	const table = chalkTable({ columns: humanColumns }, page.entries.map(toHumanRow))
+	return page.hasMore ? `${table}\nMore entries available — rerun with --offset ${page.nextOffset}.` : table
+}
+
+const toHumanRow = (entry: TenantAuthLogEntry): Record<AuthLogCell, string> => ({
+	createdAt: formatTimestamp(entry.createdAt),
+	type: humanText(entry.type),
+	success: entry.success ? 'yes' : 'no',
+	person: humanText(entry.personId ?? entry.personInputIdentifier ?? ''),
+	identity: humanText(entry.invokedByIdentityId ?? ''),
+	ip: humanText(entry.ipAddress ?? ''),
+	error: humanText(entry.errorCode ?? ''),
+})
+
+/** Raw ISO timestamps read badly in a terminal; UTC keeps the rendering reproducible. */
+const formatTimestamp = (value: string): string => {
+	const parsed = new Date(value)
+	return Number.isNaN(parsed.getTime()) ? humanText(value) : parsed.toISOString().replace('T', ' ').slice(0, 19)
+}

package/src/commands/tenant/policy/TenantMailTemplateAddCommand.ts

@@ -0,0 +1,92 @@
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { TenantMailTemplate } from '../../../lib/tenant/tenantConfig.js'
+import {
+	describeMailTemplate,
+	formatMailTemplateRef,
+	MailTemplateRef,
+	mailTypeValues,
+	parseMailType,
+	parseOptionalMailTemplateSelector,
+	readTextInput,
+} from './policyInput.js'
+import { readStdinText, StdinReader } from '../../../lib/tenant/stdin.js'
+
+type Args = {
+	type: string
+}
+
+type Options = {
+	variant?: string
+	project?: string
+	/** Declared `required()` below, so the parser rejects the run before `execute` when it is missing. */
+	subject: string
+	content?: string
+	['content-stdin']?: boolean
+	['reply-to']?: string
+	['no-layout']?: boolean
+}
+
+/**
+ * The template is upserted by the (project, type, variant) triple. Scope lives in `--project`, not in a
+ * separate command: `addProjectMailTemplate` is bound to the very same resolver and is deprecated in the
+ * SDL in favour of `addMailTemplate`, whose input already carries `projectSlug`.
+ */
+export class TenantMailTemplateAddCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+		private readonly readStdin: StdinReader = readStdinText,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Add or replace a mail template. Existing templates with the same project, type and variant are overwritten.')
+		configuration.argument('type').description(`Mail type. One of: ${mailTypeValues.join(', ')}.`)
+		configuration.option('variant').valueRequired().description('Template variant, e.g. a locale. Defaults to the unnamed variant.')
+		configuration.option('project').valueRequired().description('Project slug. Omit for a tenant-wide (global) template.')
+		configuration.option('subject').valueRequired().required().description('Mail subject.')
+		configuration.option('content').valueRequired().description('The template body as an inline string.')
+		configuration.option('content-stdin').valueNone().description('Read the template body from stdin instead of --content.')
+		configuration.option('reply-to').valueRequired().description('Reply-to address of the sent mail.')
+		configuration.option('no-layout').valueNone().description('Do not wrap the body in the default layout.')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const type = parseMailType(input.getArgument('type'))
+		const variant = parseOptionalMailTemplateSelector(input.getOption('variant'), '--variant')
+		const projectSlug = parseOptionalMailTemplateSelector(input.getOption('project'), '--project')
+		const subject = input.getOption('subject')
+		const content = await readTextInput({
+			label: 'template body',
+			inline: input.getOption('content'),
+			inlineFlag: '--content',
+			fromStdin: input.getOption('content-stdin') === true,
+			stdinFlag: '--content-stdin',
+			allowEmpty: true,
+		}, this.readStdin)
+
+		const template: TenantMailTemplate = {
+			type,
+			subject,
+			content,
+			variant,
+			projectSlug,
+			replyTo: input.getOption('reply-to'),
+			// omitted means "use the server default", which is true — only an explicit opt-out is sent
+			useLayout: input.getOption('no-layout') === true ? false : undefined,
+		}
+
+		await this.tenantClientProvider.policy().addMailTemplate(template)
+
+		const ref: MailTemplateRef = {
+			projectSlug: template.projectSlug ?? null,
+			type,
+			variant: template.variant ?? null,
+		}
+		output.data(ref, {
+			human: value => `Added mail template (${describeMailTemplate(value)}).`,
+			quiet: formatMailTemplateRef,
+		})
+	}
+}

package/src/commands/tenant/policy/TenantMailTemplateListCommand.ts

@@ -0,0 +1,50 @@
+import { Command, CommandConfiguration, Input, Output, OutputTableColumn } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { TenantMailTemplateData } from '../../../lib/tenant/clients/index.js'
+import { humanText } from '../tenantOutput.js'
+import { formatMailTemplateRef } from './policyInput.js'
+
+type Args = {}
+type Options = {}
+
+const CONTENT_PREVIEW_LENGTH = 40
+
+/** Human mode only — a full Mustache body would make the table unreadable. `--json` keeps it whole. */
+const previewContent = (value: string): string => {
+	const singleLine = humanText(value).replace(/\s+/g, ' ').trim()
+	return singleLine.length > CONTENT_PREVIEW_LENGTH ? `${singleLine.slice(0, CONTENT_PREVIEW_LENGTH - 1)}…` : singleLine
+}
+
+const columns: OutputTableColumn<TenantMailTemplateData>[] = [
+	{ field: 'projectSlug', name: 'Project' },
+	{ field: 'type', name: 'Type' },
+	{ field: 'variant', name: 'Variant' },
+	{ field: 'subject', name: 'Subject' },
+	{ field: 'useLayout', name: 'Layout' },
+	{ field: 'replyTo', name: 'Reply to' },
+	{ field: 'content', name: 'Content', format: previewContent },
+]
+
+export class TenantMailTemplateListCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('List the configured mail templates, global and project-scoped.')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const templates = await this.tenantClientProvider.policy().listMailTemplates()
+		if (output.isQuiet) {
+			output.data(templates, { quiet: rows => rows.map(formatMailTemplateRef) })
+			return
+		}
+		output.table(columns, templates, 'type')
+		if (templates.length === 0) {
+			output.info('No mail templates are configured. The built-in ones are used.')
+		}
+	}
+}

package/src/commands/tenant/policy/TenantMailTemplateRemoveCommand.ts

@@ -0,0 +1,63 @@
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { requireConfirmation } from '../../../lib/tenant/confirmation.js'
+import {
+	describeMailTemplate,
+	formatMailTemplateRef,
+	MailTemplateRef,
+	mailTypeValues,
+	parseMailType,
+	parseOptionalMailTemplateSelector,
+} from './policyInput.js'
+
+type Args = {
+	type: string
+}
+
+type Options = {
+	variant?: string
+	project?: string
+	yes?: boolean
+}
+
+/** Counterpart of `mail-template add` — the same (project, type, variant) triple addresses the row. */
+export class TenantMailTemplateRemoveCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Remove a mail template, so the built-in one is used again.')
+		configuration.argument('type').description(`Mail type. One of: ${mailTypeValues.join(', ')}.`)
+		configuration.option('variant').valueRequired().description('Template variant, e.g. a locale. Defaults to the unnamed variant.')
+		configuration.option('project').valueRequired().description('Project slug. Omit to address the tenant-wide (global) template.')
+		configuration.option('yes').valueNone().description('Do not ask for confirmation.')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const ref: MailTemplateRef = {
+			projectSlug: parseOptionalMailTemplateSelector(input.getOption('project'), '--project') ?? null,
+			type: parseMailType(input.getArgument('type')),
+			variant: parseOptionalMailTemplateSelector(input.getOption('variant'), '--variant') ?? null,
+		}
+		const description = describeMailTemplate(ref)
+		await requireConfirmation({
+			yes: input.getOption('yes') === true,
+			output,
+			warning: `Mail template (${description}) will be removed and the built-in one used instead.`,
+		})
+
+		await this.tenantClientProvider.policy().removeMailTemplate({
+			projectSlug: ref.projectSlug ?? undefined,
+			type: ref.type,
+			variant: ref.variant ?? undefined,
+		})
+
+		output.data(ref, {
+			human: value => `Removed mail template (${describeMailTemplate(value)}).`,
+			quiet: formatMailTemplateRef,
+		})
+	}
+}

package/src/commands/tenant/policy/TenantPolicyCreateCommand.ts

@@ -0,0 +1,46 @@
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { AUTH_POLICY_JSON_EXAMPLE, parseAuthPolicyInput, readTextInput } from './policyInput.js'
+import { readStdinText, StdinReader } from '../../../lib/tenant/stdin.js'
+import { humanText } from '../tenantOutput.js'
+
+type Args = {}
+
+type Options = {
+	policy?: string
+	['policy-stdin']?: boolean
+}
+
+export class TenantPolicyCreateCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+		private readonly readStdin: StdinReader = readStdinText,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Create an auth policy from an AuthPolicyInput JSON document.')
+		configuration.option('policy').valueRequired().description(`The policy as JSON, e.g. '${AUTH_POLICY_JSON_EXAMPLE}'.`)
+		configuration.option('policy-stdin').valueNone().description('Read the policy JSON from stdin instead of --policy.')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const policy = parseAuthPolicyInput(
+			await readTextInput({
+				label: 'policy',
+				inline: input.getOption('policy'),
+				inlineFlag: '--policy',
+				fromStdin: input.getOption('policy-stdin') === true,
+				stdinFlag: '--policy-stdin',
+			}, this.readStdin),
+		)
+
+		const id = await this.tenantClientProvider.policy().createAuthPolicy(policy)
+
+		output.data({ id, scope: policy.scope, project: policy.project ?? null }, {
+			human: result => `Created auth policy ${humanText(result.id)}.`,
+			quiet: result => result.id,
+		})
+	}
+}

package/src/commands/tenant/policy/TenantPolicyDeleteCommand.ts

@@ -0,0 +1,42 @@
+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
+}
+
+export class TenantPolicyDeleteCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Delete an auth policy.')
+		configuration.argument('id').description('Id of the auth policy, as printed by "tenant policy list".')
+		configuration.option('yes').valueNone().description('Do not ask for confirmation.')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const id = input.getArgument('id')
+		await requireConfirmation({
+			yes: input.getOption('yes') === true,
+			output,
+			warning: `Auth policy ${id} will be deleted. The roles it covers fall back to the tenant defaults.`,
+		})
+
+		await this.tenantClientProvider.policy().deleteAuthPolicy(id)
+
+		output.data({ id }, {
+			human: result => `Deleted auth policy ${humanText(result.id)}.`,
+			quiet: result => result.id,
+		})
+	}
+}

package/src/commands/tenant/policy/TenantPolicyListCommand.ts

@@ -0,0 +1,39 @@
+import { Command, CommandConfiguration, Input, Output, OutputTableColumn } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { RemoteAuthPolicy } from '../../../lib/tenant/clients/index.js'
+import { humanText } from '../tenantOutput.js'
+
+type Args = {}
+type Options = {}
+
+const columns: OutputTableColumn<RemoteAuthPolicy>[] = [
+	{ field: 'id', name: 'ID' },
+	{ field: 'scope', name: 'Scope' },
+	{ field: 'project', name: 'Project' },
+	{ field: 'roles', name: 'Roles', format: value => value.map(humanText).join(', ') },
+	{ field: 'mfaRequired', name: 'MFA required' },
+	{ field: 'tokenExpiration', name: 'Token expiration' },
+	{ field: 'idleTimeout', name: 'Idle timeout' },
+	{ field: 'mfaGraceDuration', name: 'MFA grace' },
+	{ field: 'rememberMeAllowed', name: 'Remember me' },
+]
+
+export class TenantPolicyListCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('List the configured auth policies (per-role MFA and session policy).')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const policies = await this.tenantClientProvider.policy().listAuthPolicies()
+		output.table(columns, policies, 'id')
+		if (policies.length === 0) {
+			output.info('No auth policies are configured. MFA enforcement is inert.')
+		}
+	}
+}

package/src/commands/tenant/policy/TenantPolicyUpdateCommand.ts

@@ -0,0 +1,51 @@
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { AUTH_POLICY_JSON_EXAMPLE, parseAuthPolicyInput, readTextInput } from './policyInput.js'
+import { readStdinText, StdinReader } from '../../../lib/tenant/stdin.js'
+import { humanText } from '../tenantOutput.js'
+
+type Args = {
+	id: string
+}
+
+type Options = {
+	policy?: string
+	['policy-stdin']?: boolean
+}
+
+export class TenantPolicyUpdateCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+		private readonly readStdin: StdinReader = readStdinText,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Replace an auth policy with the given AuthPolicyInput JSON document.')
+		configuration.argument('id').description('Id of the auth policy, as printed by "tenant policy list".')
+		configuration.option('policy').valueRequired().description(`The policy as JSON, e.g. '${AUTH_POLICY_JSON_EXAMPLE}'.`)
+		configuration.option('policy-stdin').valueNone().description('Read the policy JSON from stdin instead of --policy.')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const id = input.getArgument('id')
+		// the mutation replaces the whole row, so the JSON must carry every field the policy should keep
+		const policy = parseAuthPolicyInput(
+			await readTextInput({
+				label: 'policy',
+				inline: input.getOption('policy'),
+				inlineFlag: '--policy',
+				fromStdin: input.getOption('policy-stdin') === true,
+				stdinFlag: '--policy-stdin',
+			}, this.readStdin),
+		)
+
+		await this.tenantClientProvider.policy().updateAuthPolicy(id, policy)
+
+		output.data({ id, scope: policy.scope, project: policy.project ?? null }, {
+			human: result => `Updated auth policy ${humanText(result.id)}.`,
+			quiet: result => result.id,
+		})
+	}
+}

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

@@ -0,0 +1,9 @@
+// Commands of `tenant policy`, `tenant mail-template` and `tenant auth-log` — the whole policy domain.
+export * from './TenantAuthLogCommand.js'
+export * from './TenantMailTemplateAddCommand.js'
+export * from './TenantMailTemplateListCommand.js'
+export * from './TenantMailTemplateRemoveCommand.js'
+export * from './TenantPolicyCreateCommand.js'
+export * from './TenantPolicyDeleteCommand.js'
+export * from './TenantPolicyListCommand.js'
+export * from './TenantPolicyUpdateCommand.js'