@contember/cli 2.2.0-alpha.1 → 2.2.0-alpha.10

package/src/lib/tenant/confirmation.ts

@@ -0,0 +1,32 @@
+import { CliError, ExitCode, Output } from '@contember/cli-common'
+import { promptConfirm } from '../prompt/index.js'
+
+export interface ConfirmationArgs {
+	readonly yes: boolean
+	readonly output: Output
+	/** What is about to happen, shown above the prompt. */
+	readonly warning: string
+}
+
+/**
+ * The one destructive-action guard of the tenant commands. `--yes` skips the prompt; without a TTY there
+ * is nobody to answer it, so the run fails fast instead of hanging a CI job. Declining throws as well, so
+ * a caller never has to turn a boolean into an exit code and an agent always gets a typed error.
+ */
+export const requireConfirmation = async ({ yes, output, warning }: ConfirmationArgs): Promise<void> => {
+	if (yes) {
+		return
+	}
+	if (!output.canPrompt()) {
+		throw new CliError('TTY not available. Pass --yes to confirm execution.', {
+			code: 'TTY_UNAVAILABLE',
+			exitCode: ExitCode.InputError,
+		})
+	}
+	output.warn(warning)
+	output.info('(to skip this dialog, you can pass the --yes option)')
+	const confirmed = await promptConfirm(output, { message: 'Do you want to continue?' })
+	if (!confirmed) {
+		throw new CliError('Aborted by the user.', { code: 'ABORTED', exitCode: ExitCode.InputError })
+	}
+}

package/src/lib/tenant/input/index.ts

@@ -0,0 +1,2 @@
+export * from './pagination.js'
+export * from './value.js'

package/src/lib/tenant/input/pagination.ts

@@ -0,0 +1,39 @@
+import { CliError, ExitCode } from '@contember/cli-common'
+
+/** GraphQL `Int` is a signed 32-bit integer. Pagination values are non-negative. */
+export const GRAPHQL_INT_MAX = 2_147_483_647
+
+/** Parses an optional non-negative integer pagination offset. */
+export const parsePaginationOffset = (value: string | undefined, flag = '--offset'): number | undefined =>
+	parsePaginationInteger(value, flag, 'offset', 0)
+
+/** Parses an optional positive integer pagination limit. */
+export const parsePaginationLimit = (value: string | undefined, flag = '--limit'): number | undefined =>
+	parsePaginationInteger(value, flag, 'limit', 1)
+
+const parsePaginationInteger = (
+	value: string | undefined,
+	flag: string,
+	kind: 'offset' | 'limit',
+	minimum: number,
+): number | undefined => {
+	if (value === undefined) {
+		return undefined
+	}
+	const parsed = Number(value)
+	if (
+		!/^(?:0|[1-9]\d*)$/.test(value)
+		|| !Number.isSafeInteger(parsed)
+		|| parsed < minimum
+		|| parsed > GRAPHQL_INT_MAX
+	) {
+		const requirement = kind === 'offset'
+			? `a non-negative GraphQL Int (maximum ${GRAPHQL_INT_MAX})`
+			: `a positive GraphQL Int (maximum ${GRAPHQL_INT_MAX})`
+		throw new CliError(`${flag} must be ${requirement}.`, {
+			code: kind === 'offset' ? 'INVALID_PAGINATION_OFFSET' : 'INVALID_PAGINATION_LIMIT',
+			exitCode: ExitCode.InputError,
+		})
+	}
+	return parsed
+}

package/src/lib/tenant/input/value.ts

@@ -0,0 +1,149 @@
+import { CliError, ExitCode } from '@contember/cli-common'
+import { readStdinText, type StdinReader } from '../stdin.js'
+
+interface InputSourceBase<Name extends string> {
+	/** Identifies the semantic value, for example `password` or `password-hash`. */
+	readonly name: Name
+	/** Identifies the selected option without including its submitted value. */
+	readonly flag: string
+}
+
+export interface LiteralInputSource<Name extends string = string> extends InputSourceBase<Name> {
+	readonly kind: 'literal'
+	readonly value: string
+}
+
+export interface EnvironmentInputSource<Name extends string = string> extends InputSourceBase<Name> {
+	readonly kind: 'environment'
+	readonly variable: string
+}
+
+export interface StdinInputSource<Name extends string = string> extends InputSourceBase<Name> {
+	readonly kind: 'stdin'
+}
+
+/** One explicitly selected input source. Unselected options must not be included. */
+export type TenantInputSource<Name extends string = string> =
+	| LiteralInputSource<Name>
+	| EnvironmentInputSource<Name>
+	| StdinInputSource<Name>
+
+export type TrailingLineEnding = 'preserve' | 'remove-one'
+
+export interface TenantInputOptions {
+	/** A non-sensitive description used in errors, for example `project secret`. */
+	readonly label: string
+	readonly allowEmpty?: boolean
+	readonly trailingLineEnding?: TrailingLineEnding
+}
+
+export interface TenantInputDependencies {
+	readonly readStdin?: StdinReader
+	readonly readEnvironment?: (name: string) => string | undefined
+}
+
+export interface ResolvedTenantInput<Name extends string = string> {
+	readonly name: Name
+	readonly kind: TenantInputSource<Name>['kind']
+	readonly value: string
+}
+
+export const literalInput = <Name extends string>(name: Name, flag: string, value: string): LiteralInputSource<Name> => ({
+	kind: 'literal',
+	name,
+	flag,
+	value,
+})
+
+export const environmentInput = <Name extends string>(name: Name, flag: string, variable: string): EnvironmentInputSource<Name> => ({
+	kind: 'environment',
+	name,
+	flag,
+	variable,
+})
+
+export const stdinInput = <Name extends string>(name: Name, flag: string): StdinInputSource<Name> => ({
+	kind: 'stdin',
+	name,
+	flag,
+})
+
+/** Resolves exactly one explicitly selected source. */
+export const resolveRequiredTenantInput = async <Name extends string>(
+	sources: readonly TenantInputSource<Name>[],
+	options: TenantInputOptions,
+	dependencies: TenantInputDependencies = {},
+): Promise<ResolvedTenantInput<Name>> => {
+	const source = selectSource(sources, options.label, true)
+	return await resolveSelectedSource(source, options, dependencies)
+}
+
+/** Resolves at most one explicitly selected source without reading stdin when none was selected. */
+export const resolveOptionalTenantInput = async <Name extends string>(
+	sources: readonly TenantInputSource<Name>[],
+	options: TenantInputOptions,
+	dependencies: TenantInputDependencies = {},
+): Promise<ResolvedTenantInput<Name> | undefined> => {
+	const source = selectSource(sources, options.label, false)
+	return source === undefined ? undefined : await resolveSelectedSource(source, options, dependencies)
+}
+
+function selectSource<Name extends string>(
+	sources: readonly TenantInputSource<Name>[],
+	label: string,
+	required: true,
+): TenantInputSource<Name>
+function selectSource<Name extends string>(
+	sources: readonly TenantInputSource<Name>[],
+	label: string,
+	required: false,
+): TenantInputSource<Name> | undefined
+function selectSource<Name extends string>(
+	sources: readonly TenantInputSource<Name>[],
+	label: string,
+	required: boolean,
+): TenantInputSource<Name> | undefined {
+	if (sources.length > 1) {
+		throw inputError(`Select only one input source for ${label}: ${sources.map(source => source.flag).join(', ')}.`, 'AMBIGUOUS_INPUT_SOURCE')
+	}
+	const source = sources[0]
+	if (source === undefined && required) {
+		throw inputError(`Select an input source for ${label}.`, 'MISSING_INPUT_SOURCE')
+	}
+	return source
+}
+
+const resolveSelectedSource = async <Name extends string>(
+	source: TenantInputSource<Name>,
+	options: TenantInputOptions,
+	dependencies: TenantInputDependencies,
+): Promise<ResolvedTenantInput<Name>> => {
+	const value = await readSource(source, dependencies)
+	const normalized = options.trailingLineEnding === 'remove-one' ? removeOneTrailingLineEnding(value) : value
+	if (normalized === '' && options.allowEmpty !== true) {
+		throw inputError(`${source.flag} resolved to an empty value for ${options.label}.`, 'EMPTY_INPUT_VALUE')
+	}
+	return { name: source.name, kind: source.kind, value: normalized }
+}
+
+const readSource = async <Name extends string>(source: TenantInputSource<Name>, dependencies: TenantInputDependencies): Promise<string> => {
+	switch (source.kind) {
+		case 'literal':
+			return source.value
+		case 'environment': {
+			const value = (dependencies.readEnvironment ?? readEnvironment)(source.variable)
+			if (value === undefined) {
+				throw inputError(`Environment variable ${source.variable} selected by ${source.flag} is not set.`, 'INPUT_ENV_NOT_SET')
+			}
+			return value
+		}
+		case 'stdin':
+			return await (dependencies.readStdin ?? readStdinText)()
+	}
+}
+
+const readEnvironment = (name: string): string | undefined => process.env[name]
+
+const removeOneTrailingLineEnding = (value: string): string => value.replace(/(?:\r\n|\n)$/, '')
+
+const inputError = (message: string, code: string): CliError => new CliError(message, { code, exitCode: ExitCode.InputError })

package/src/lib/tenant/stdin.ts

@@ -0,0 +1,16 @@
+/** Reads the whole stdin. Injected into the commands so a test never has to touch the real stream. */
+export type StdinReader = () => Promise<string>
+
+/**
+ * Reads stdin to the end, verbatim. Only ever reached behind an explicit `--*-stdin` flag, so a normal
+ * run never blocks on it — a command that reads stdin "just in case" hangs every non-TTY caller.
+ */
+export const readStdinText: StdinReader = async () => {
+	const stream: AsyncIterable<string | Uint8Array> = process.stdin
+	const decoder = new TextDecoder()
+	let text = ''
+	for await (const chunk of stream) {
+		text += typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true })
+	}
+	return text + decoder.decode()
+}

package/src/lib/tenant/tenantConfig.ts

@@ -1,4 +1,5 @@
 import type {
+	AuthPolicyInput,
 	ConfigCaptchaInput,
 	ConfigInput,
 	ConfigLoginInput,
@@ -8,50 +9,36 @@ import type {
 	ConfigRateLimitWindowInput,
 	IDPOptions,
 	MailTemplate,
+	MailType,
 } from '@contember/graphql-client-tenant'
 
-// Enums and leaf input shapes are re-derived from the generated tenant client
-// (`@contember/graphql-client-tenant`, generated from `tenant.graphql`), so they
-// stay in sync with the schema. The only thing layered on top is `| null` on the
-// fields where the API treats an explicit `null`/`''` as "clear/disable" — the
-// codegen renders nullable inputs as optional only and drops the `| null`.
-export type { CaptchaProvider, ConfigPolicy, MailType } from '@contember/graphql-client-tenant'
+// These aliases keep tenant config authoring aligned with the GraphQL schema.
+// The generator preserves nullable input fields, including explicit `null`.
+export type { AuthPolicyScope, CaptchaProvider, ConfigPolicy, MailType } from '@contember/graphql-client-tenant'
 
 /**
  * ISO 8601 duration string, e.g. `"P1D"` (1 day) or `"PT5M"` (5 minutes).
  */
 export type Interval = string
 
-/** Adds `| null` to the given keys of an otherwise non-nullable generated input. */
-type WithNullable<T, K extends keyof T> = Omit<T, K> & { readonly [P in K]?: T[P] | null }
+export type TenantPasswordConfig = ConfigPasswordInput
 
-export type TenantPasswordConfig = WithNullable<ConfigPasswordInput, 'pattern'>
+export type TenantLoginConfig = ConfigLoginInput
 
-export type TenantLoginConfig = WithNullable<ConfigLoginInput, 'maxTokenExpiration'>
-
-export type TenantPasswordlessConfig = WithNullable<ConfigPasswordlessInput, 'url'>
+export type TenantPasswordlessConfig = ConfigPasswordlessInput
 
 /**
  * `provider: null` disables captcha verification.
  * `secret` is write-only: `null`/omitted leaves the stored value unchanged, `''` clears it.
  */
-export type TenantCaptchaConfig = WithNullable<ConfigCaptchaInput, 'provider' | 'secret' | 'threshold'>
+export type TenantCaptchaConfig = ConfigCaptchaInput
 
 export type TenantRateLimitWindow = ConfigRateLimitWindowInput
 
 export type TenantRateLimitsConfig = ConfigRateLimitsInput
 
-/**
- * Maps to the tenant `configure(config: ConfigInput!)` mutation. New config
- * groups added to the schema flow through automatically; only the groups that
- * need `| null` overrides are pinned.
- */
-export type TenantGlobalConfig = Omit<ConfigInput, 'password' | 'login' | 'passwordless' | 'captcha'> & {
-	readonly password?: TenantPasswordConfig
-	readonly login?: TenantLoginConfig
-	readonly passwordless?: TenantPasswordlessConfig
-	readonly captcha?: TenantCaptchaConfig
-}
+/** Maps to the tenant `configure(config: ConfigInput!)` mutation. */
+export type TenantGlobalConfig = ConfigInput
 
 export type TenantIdpOptions = IDPOptions
 
@@ -72,7 +59,138 @@ export interface TenantIdpConfig {
 }
 
 /** Maps to the `addMailTemplate(template: MailTemplate!)` mutation. */
-export type TenantMailTemplate = WithNullable<MailTemplate, 'projectSlug' | 'replyTo'>
+export type TenantMailTemplate = MailTemplate
+
+/**
+ * A per-role MFA / session policy. `project` is a project slug, required for
+ * `scope: 'project'` and rejected for `scope: 'global'` (validated server-side).
+ *
+ * Unlike identity providers there is no server-side slug, so entries are matched
+ * against existing rows by `scope` + `project` + the `roles` **set** (order does
+ * not matter). Editing `roles` therefore reads as a different policy: a new row
+ * is created and the old one is left in place — see `TenantConfigApplier`.
+ */
+export type TenantAuthPolicy = AuthPolicyInput
+
+export interface TenantCustomRoleRoleConstraint {
+	/** Exhaustive: every role observed at the constrained position must appear here. Not a filter, and there is no `denied` counterpart. */
+	readonly allowed: readonly string[]
+}
+
+export interface TenantCustomRoleTarget {
+	readonly globalRoles: TenantCustomRoleRoleConstraint
+	readonly projectMemberships: 'none' | 'any'
+}
+
+export interface TenantCustomRoleRoleInputConfig {
+	readonly roles: TenantCustomRoleRoleConstraint
+}
+
+export interface TenantCustomRoleTargetConfig {
+	readonly target: TenantCustomRoleTarget
+}
+
+export interface TenantCustomRoleMutationConfig extends TenantCustomRoleRoleInputConfig, TenantCustomRoleTargetConfig {
+	readonly allowSelf: boolean
+}
+
+export interface TenantCustomRoleGlobalApiKeyConfig extends TenantCustomRoleRoleInputConfig {
+	/** Custom roles may not create keys trusted to forward client info. */
+	readonly allowTrustForwardedClientInfo: false
+}
+
+export interface TenantCustomRoleChangeProfileConfig extends TenantCustomRoleTargetConfig {
+	readonly fields: {
+		readonly allowed: readonly ('name' | 'email')[]
+	}
+}
+
+export interface TenantCustomRoleCreateSessionTokenConfig extends TenantCustomRoleTargetConfig {
+	readonly session: {
+		readonly maxExpirationMinutes: number
+		readonly allowTrustForwardedClientInfo: boolean
+	}
+}
+
+export interface TenantCustomRoleMailTemplateConfig {
+	readonly global: boolean
+	readonly projects: readonly string[]
+	readonly types: readonly MailType[]
+}
+
+export type TenantCustomRoleConfigFreePermission =
+	| 'system:configure'
+	| 'system:viewConfig'
+	| 'system:viewAuthLog'
+	| 'person:view'
+	| 'person:list'
+	| 'entrypoint:deployEntrypoint'
+	| 'apiKey:list'
+	| 'idp:disable'
+	| 'idp:enable'
+	| 'idp:list'
+	| 'customRole:view'
+	| 'identity:viewPermissions'
+
+export type TenantCustomRoleTargetPermission =
+	| 'person:disable'
+	| 'person:forceSignOut'
+	| 'person:resetMfa'
+	| 'person:viewSessions'
+	| 'person:viewIdp'
+	| 'person:changePassword'
+
+export type TenantCustomRoleMutationPermission =
+	| 'identity:addGlobalRoles'
+	| 'identity:removeGlobalRoles'
+
+export type TenantCustomRoleMailTemplatePermission =
+	| 'mailTemplate:add'
+	| 'mailTemplate:remove'
+	| 'mailTemplate:list'
+
+/**
+ * A custom-role grant discriminated by `permission`. Configured permissions
+ * require their exact action-specific config; config-free permissions reject it.
+ */
+export type TenantCustomRoleGrant =
+	| {
+		readonly permission: TenantCustomRoleConfigFreePermission
+		readonly config?: never
+	}
+	| {
+		readonly permission: 'person:signUp'
+		readonly config: TenantCustomRoleRoleInputConfig
+	}
+	| {
+		readonly permission: TenantCustomRoleTargetPermission
+		readonly config: TenantCustomRoleTargetConfig
+	}
+	| {
+		readonly permission: 'person:changeProfile'
+		readonly config: TenantCustomRoleChangeProfileConfig
+	}
+	| {
+		readonly permission: 'person:createSessionToken'
+		readonly config: TenantCustomRoleCreateSessionTokenConfig
+	}
+	| {
+		readonly permission: TenantCustomRoleMutationPermission
+		readonly config: TenantCustomRoleMutationConfig
+	}
+	| {
+		readonly permission: 'apiKey:createGlobal'
+		readonly config: TenantCustomRoleGlobalApiKeyConfig
+	}
+	| {
+		readonly permission: TenantCustomRoleMailTemplatePermission
+		readonly config: TenantCustomRoleMailTemplateConfig
+	}
+
+export interface TenantCustomRoleConfig {
+	readonly description?: string | null
+	readonly grants: readonly TenantCustomRoleGrant[]
+}
 
 /**
  * Declarative tenant configuration. Applied idempotently by
@@ -83,6 +201,9 @@ export interface TenantConfig {
 	/** Identity providers keyed by slug. */
 	identityProviders?: Record<string, TenantIdpConfig>
 	mailTemplates?: TenantMailTemplate[]
+	authPolicies?: TenantAuthPolicy[]
+	/** Custom roles keyed by slug. Missing roles are created; existing roles are replaced. */
+	customRoles?: Record<string, TenantCustomRoleConfig>
 }
 
 /**